Reports

Tables, templates and the agents vs humans summary.

Generated

This page is generated from api/openapi/v1.yaml (OpenAPI 3.1.0, API version 1.0.0).

Run a report (any dimensions × metrics × filters × actor × dates)

POST/v1/properties/{pid}/reports/run

Scope: reports:read. Builds any table from the catalog. Every query is bounded by property and date range. Use actor to split agents vs humans, or a filters tree for anything else.

Parameters

Name	In	Type	Required	Description
pid	path	string	yes	Property id.

Request body

Field	Type	Required	Description
date_range	"last_7_days" | "last_28_days" | "last_90_days" | "this_month" | "last_month" | "yesterday" | "today" or object		A preset or an explicit range in the property time zone. Default last_28_days.
compare	"previous_period" | "previous_year" or object
actor	"all" | "humans_and_agents" | "humans" | "action_agents" | "indexing_bots" | "mixed_sessions"		Who to count: all, humans_and_agents (excludes indexing bots), humans, action_agents (AI agents and automation), indexing_bots (crawlers, AI readers, monitoring) or mixed_sessions.
scope	"event" | "session" | "segment" | "page" | "user" | "element"
dimensions	array of string
metrics	array of string	yes
filters	object or object or object or object		A filter tree. Leaf {field, op, value}, or {and: [...]}, {or: [...]}, {not: {...}}.
segment_id	string
order_by	array of object
limit	integer

Responses

Status	Description
200	Report result.
400	Invalid body or query (invalid_request), with errors[] for validation failures.
401	Missing, invalid, expired or revoked API key (unauthorized).
403	The key lacks the required scope (forbidden_scope).
404	Unknown endpoint, or a property / object that does not exist or is not accessible with this key (not_found).
429	Rate limit exceeded (rate_limited). Wait Retry-After seconds.

Response fields

Field	Type	Required	Description
columns	array of object	yes
rows	array of object	yes
totals	object | null
compare	object
meta	object	yes

Run a built-in report template

POST/v1/properties/{pid}/templates/{id}/run

Scope: reports:read. Runs every widget of the template. Widgets that need a feature your plan lacks come back with an error instead of a result.

Parameters

Name	In	Type	Required	Description
pid	path	string	yes	Property id.
id	path	string	yes	Template id (see GET /templates), e.g. humans_vs_agents.

Request body

Field	Type	Required	Description
date_range	"last_7_days" | "last_28_days" | "last_90_days" | "this_month" | "last_month" | "yesterday" | "today" or object		A preset or an explicit range in the property time zone. Default last_28_days.
compare	"previous_period" | "previous_year" or object
actor	"all" | "humans_and_agents" | "humans" | "action_agents" | "indexing_bots" | "mixed_sessions"		Who to count: all, humans_and_agents (excludes indexing bots), humans, action_agents (AI agents and automation), indexing_bots (crawlers, AI readers, monitoring) or mixed_sessions.

{
  "date_range": "last_28_days",
  "actor": "all"
}

Responses

Status	Description
200	Widgets with their results.
400	Invalid body or query (invalid_request), with errors[] for validation failures.
401	Missing, invalid, expired or revoked API key (unauthorized).
403	The key lacks the required scope (forbidden_scope).
404	Unknown endpoint, or a property / object that does not exist or is not accessible with this key (not_found).

Response fields

Field	Type	Required	Description
template	object
widgets	array of object
meta	object

Agents vs humans vs bots headline

GET/v1/properties/{pid}/summary

Scope: reports:read. Sessions by navigation mode (agent, mixed, human, bot), activity by actor family, top agents, and the share of the AI Assistants channel.

Parameters

Name	In	Type	Required	Description
pid	path	string	yes	Property id.
date_range	query	"last_7_days" | "last_28_days" | "last_90_days" | "this_month" | "last_month" | "yesterday" | "today"		Date preset. Ignored when start and end are given.
start	query	string
end	query	string
actor	query	"all" | "humans_and_agents" | "humans" | "action_agents" | "indexing_bots" | "mixed_sessions"

Responses

Status	Description
200	Summary.
400	Invalid body or query (invalid_request), with errors[] for validation failures.
401	Missing, invalid, expired or revoked API key (unauthorized).
403	The key lacks the required scope (forbidden_scope).
404	Unknown endpoint, or a property / object that does not exist or is not accessible with this key (not_found).

Response fields

Field	Type	Required	Description
sessions_by_navigation_mode	array of object
by_actor_family	array of object
top_agents	array of object
agent_session_share	number		Share of sessions with an agent (agent + mixed).
ai_assistants_channel	object
totals	object | null
meta	object