Agents & bots

Mixed sessions, pages read by AI and crawlers, realtime.

Generated

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

Who is on the site now — agents, humans and bots

GET/v1/properties/{pid}/realtime

Scope: realtime:read. Last N minutes (default 30) by actor family, active users of the last 5 minutes, live agents and top pages.

Parameters

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

Responses

Status	Description
200	Realtime snapshot.
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
minutes	integer
active_now	object		Users active in the last 5 minutes, by actor family.
live_agents	array of object
timeline	array of object
top_pages	array of object

Clicked elements catalog

GET/v1/properties/{pid}/elements

Scope: reports:read. Every clicked element (CSS selector, data-ah-name, text) with clicks by agents and humans — the building blocks of element funnel steps.

Parameters

Name	In	Type	Required	Description
pid	path	string	yes	Property id.
q	query	string		Search in selector, name and text.
hostname	query	string
limit	query	integer

Responses

Status	Description
200	Elements.
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
data	array of object

Sessions where an agent and a human took turns

POST/v1/properties/{pid}/agents/mixed-sessions

Scope: reports:read. Plan feature mixed_sessions (Growth and above). Each session comes with its ordered actor segments (who did what, in which order). Default range: last 7 days.

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.
navigation_modes	array of "agent" | "mixed" | "human" | "bot"
limit	integer

Responses

Status	Description
200	Sessions with segments.
401	Missing, invalid, expired or revoked API key (unauthorized).
402	The plan does not include the feature (plan_required) or a monthly quota is used up (quota_exceeded). required_plan is the cheapest plan that unlocks it.
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	array of object
meta	object

Agent readiness funnel — where agents stop while humans go on

POST/v1/properties/{pid}/agents/friction

Scope: reports:read. Plan feature agent_funnels (Growth and above). Runs the same multi-page funnel for action agents and humans (indexing bots excluded), finds the blocking step (largest gap between the human and the agent pass-through rate), and diagnoses it: elements clicked on that page by agents vs humans, retries, synthetic clicks, time on step, agents most affected, suggested fixes and the upside of a fix. Without steps or funnel_id, uses the default shop journey (home and landing pages, search, product pages, add to cart, shipping, delivery slot, payment, order), measured as the furthest stage each session reached. Custom steps run as an ordered funnel. Default range: last 28 days.

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.
steps	array of object or object or object
funnel_id	string		Use the steps of a saved funnel.
window_seconds	integer
mode	"furthest" | "ordered"		furthest: a session counts at every stage up to the furthest it reached. ordered: steps in order within window_seconds. Default: furthest for the default journey, ordered for custom steps.

Responses

Status	Description
200	Steps per actor, blocking step and diagnosis.
401	Missing, invalid, expired or revoked API key (unauthorized).
402	The plan does not include the feature (plan_required) or a monthly quota is used up (quota_exceeded). required_plan is the cheapest plan that unlocks it.
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
funnel	object
spec	object
steps	array of object
blocking_step	object | null		Null when no step shows a gap above the threshold with enough sessions.
totals	object
cached	boolean
meta	object

Pages read by AI assistants and crawlers

GET/v1/properties/{pid}/bots/pages

Scope: reports:read. Plan feature server_side_bots (Pro and above). Per page: AI readers (ChatGPT-User, Claude-User, Perplexity-User…), AI crawlers, search crawlers, which bots, and verified vs spoofed hits.

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
path_prefix	query	string
sort	query	"ai_reads" | "search_crawls" | "human_pageviews"
limit	query	integer

Responses

Status	Description
200	Pages.
401	Missing, invalid, expired or revoked API key (unauthorized).
402	The plan does not include the feature (plan_required) or a monthly quota is used up (quota_exceeded). required_plan is the cheapest plan that unlocks it.
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
data	array of object
meta	object