Reports and templates

Discover the catalog

GET /catalog lists every dimension and metric with its ID, label, scope (event, session, segment, page, user, element), type and description. GET /templates lists the 30 built-in reports, GET /templates/{id} one of them with its widgets.

Run any report

POST /properties/{pid}/reports/run

{
  "date_range": "last_28_days",
  "compare": "previous_period",
  "actor": "humans_and_agents",
  "dimensions": ["channel_group", "navigation_mode"],
  "metrics": ["sessions", "conversions", "revenue"],
  "filters": { "and": [{ "field": "device_type", "op": "eq", "value": "mobile" }] },
  "order_by": [{ "field": "sessions", "dir": "desc" }],
  "limit": 20
}

Field
metrics	1 to 20 metric IDs from the catalog (required)
dimensions	0 to 5 dimension IDs
scope	Optional: force the level of the report (event, session, segment, page, user, element); otherwise deduced from the metrics
filters	A tree: leaf {field, op, value} or {and: […]}, {or: […]}, {not: {…}}. Operators: eq, neq, contains, not_contains, starts_with, regex, not_regex, in, not_in, gt, gte, lt, lte
segment_id	A saved segment to apply
order_by	Up to 5 {field, dir: "asc" | "desc"}
limit	1 to 10,000 rows (default 1,000)

Response:

{
  "columns": [
    { "id": "channel_group", "label": "Channel", "kind": "dimension" },
    { "id": "navigation_mode", "label": "Navigation mode", "kind": "dimension" },
    { "id": "sessions", "label": "Sessions", "kind": "metric", "format": "integer" },
    { "id": "conversions", "label": "Conversions", "kind": "metric", "format": "integer" },
    { "id": "revenue", "label": "Revenue", "kind": "metric", "format": "currency" }
  ],
  "rows": [["Organic Search", "human", 4210, 71, 6120.5], ["AI Assistants", "mixed", 212, 41, 5388.0]],
  "totals": { "sessions": 9874, "conversions": 233, "revenue": 24310.2 },
  "compare": { … },
  "meta": { "property_id": "AH-1A2B3C", "timezone": "Europe/Paris", "date_range": { "start": "2026-10-02", "end": "2026-10-29" }, "actor": "humans_and_agents", "scope": "session", "cached": false }
}

Dimensions and metrics must come from the catalog; values are always sent to the database as parameters, never concatenated into queries.

Run a template

POST /properties/{pid}/templates/{id}/run with {date_range, actor?, compare?} returns every widget of the template with its result, for example humans_vs_agents, traffic_acquisition, agent_funnels or ai_reads.

Headline summary

GET /properties/{pid}/summary?date_range=last_28_days&actor=all returns the agents vs humans vs bots headline: sessions_by_navigation_mode, by_actor_family, top_agents, agent_session_share, ai_assistants_channel and totals. It is the quickest way to feed a KPI dashboard.