Funnels & paths

Funnels with page, event and clicked-element steps; paths; retention.

Generated

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

Run an ad-hoc funnel (page, event and clicked-element steps)

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

Scope: reports:read. Plan feature agent_funnels (Growth and above). Break it down by actor_family or navigation_mode to compare agents and humans step by step.

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.
steps	array of object or object or object	yes
unit	"session" | "visitor"
window	integer		Conversion window in seconds (alias of window_seconds).
window_seconds	integer
mode	"closed" | "open"
strict_order	boolean
breakdown	"none" | "actor_family" | "actor_type" | "actor_name" | "navigation_mode" | "device_type" | "channel_group" | "country"

{
  "date_range": "last_28_days",
  "breakdown": "actor_family",
  "steps": [
    {
      "type": "page",
      "path": "/p/*",
      "label": "Product page"
    },
    {
      "type": "element",
      "el_name": "add-to-cart",
      "label": "Add to cart"
    },
    {
      "type": "page",
      "path": "/checkout/shipping"
    },
    {
      "type": "element",
      "el_name": "delivery-slot-picker",
      "label": "Delivery slot"
    },
    {
      "type": "event",
      "name": "purchase"
    }
  ]
}

Responses

Status	Description
200	Funnel steps per breakdown value.
400	Invalid body or query (invalid_request), with errors[] for validation failures.
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
breakdowns	array of object
cached	boolean
meta	object

Run a saved funnel

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

Scope: reports:read. Plan feature agent_funnels.

Parameters

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

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.

Responses

Status	Description
200	Funnel result.
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
breakdowns	array of object
cached	boolean
meta	object

Next or previous pages and clicked elements

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

Scope: reports:read. Plan feature paths (Growth and above). With split_by_actor, nodes carry the actor family to show agent ↔ human hand-offs.

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.
node	"page" | "element" | "event" | "page_and_element"
direction	"next" | "previous"
start	string		Starting page, element label or event. Empty = session start.
depth	integer
split_by_actor	boolean
collapse_repeats	boolean
limit	integer

{
  "date_range": "last_7_days",
  "node": "page_and_element",
  "direction": "next",
  "start": "/checkout/shipping",
  "depth": 4,
  "actor": "action_agents"
}

Responses

Status	Description
200	Paths with sunburst / sankey shapes.
400	Invalid body or query (invalid_request), with errors[] for validation failures.
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
rows	array of object
meta	object

Cohorts and retention

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

Scope: reports:read. Plan feature cohorts (Pro and above). Default range: last 90 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.
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.
granularity	"day" | "week" | "month"

Responses

Status	Description
200	Retention matrix rows.
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
rows	array of object
meta	object