Docs

Reports

Templates, AI-built and hand-built reports, server PDF, and the events the executive usage template expects.

A report is a printable document over one date range: sections of panels, with summary panels the AI writes from the other panels’ real results.

Structure

TypeScript

type Report  = { name; project_id; source: "manual"|"ai"|"template"; template; range; filters; segment_id?;
                theme: { title?, subtitle?, brand?, color?, logo_url? }; sections: Section[] };
type Section = { title; description?; panels: Panel[] };
type Panel   = { type: "summary"|"kpis"|"chart"|"table"|"map"|"text"; title; w: 3|4|6|8|12;
                 spec?: QuerySpec; kpis?: QuerySpec[]; viz?: Viz | "hbar";
                 prompt?: string;   // summary: what the narrative should cover
                 text?: string };   // text: markdown you write

Three ways to build one

How	Endpoint
From a template: `executive_usage`, `weekly_product`, `acquisition`, `ux_quality` (each adapts to the events the project sends)	`POST /api/reports/from-template`
From a sentence: the AI builds sections and panels from the catalog, summary first	`POST /api/reports/generate`
By hand, or one panel from a sentence (“top brokers viewed, horizontal bar”)	`POST /api/reports`, `POST /api/reports/{id}/panels/suggest`

Rendering, print and PDF

POST /api/reports/{id}/render runs every panel, then writes the narratives (rules fallback without a model), cached ten minutes per report and range. The console’s print route lays the report out for A4 and marks the page ready only after every panel has painted. GET /api/reports/{id}/pdf prints that route with headless Chromium.

pip install playwright && playwright install chromium
export CLICKIQ_CONSOLE_URL=https://clickiq.example.com     # where the console's print route is served
# CLICKIQ_PDF=off  → the API answers 501 and the console uses the browser's print-to-PDF

Snapshots (POST /api/reports/{id}/snapshots) keep a render and its PDF in your object store: a record of what was sent.

Print view of the Insurance 360 executive usage report on a white page with an INSIGHTCLICKIQ header rule, period and comparison dates, the AI executive summary with four callouts, and the start of the Users section. — The same report rendered as a clean A4-style page, with no console around it. This is the page that becomes the PDF.

Person traits and geography

user.<trait> is a property anywhere a property goes, read from the traits passed to identify (manager, team, division, department, branch, role, name). A map panel declares its level through spec.breakdown: country (world), region (US states) or city (a ranked list over a world backdrop).

Instrumenting for the executive usage report

The template renders with no further configuration when the application sends these events. This is the taxonomy from the client-360 instrumentation guide, live in the Insurance 360 demo project.