Funnels
Create, manage, and run funnel configurations through the REST API.
Funnels measure how many people, sessions, or events complete a series of steps. Results follow the saved definition's counting mode and include per-step counts, rates, and samples of visitors and sessions for the date window. When a funnel counts events, ratios can exceed 100% because they describe event volume, not people converting. The Funnels guide shows the same report in the app.
GET/rest/v1/funnels
Ours Privacy API key
In: header
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/rest/v1/funnels"{ "entities": [ { "funnelId": "cc36c810-1122-4842-933f-6c41b39cda1a", "name": "string", "description": "string", "queryDefinition": { "version": 1, "kind": "funnel", "identity": "session", "counting": "unique", "order": "ordered", "reentry": "first", "windowMs": 1, "steps": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } } ], "entryFilter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } }, "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, "watched": true, "status": "READY", "reportDateRange": { "from": "string", "to": "string" }, "createdAt": "string", "updatedAt": "string" } ], "unavailableCount": 0, "warnings": [ "string" ]}POST/rest/v1/funnels
Ours Privacy API key
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/rest/v1/funnels" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "queryDefinition": { "version": 1, "kind": "funnel", "identity": "session", "counting": "unique", "order": "ordered", "reentry": "first", "windowMs": 1, "steps": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string" }, { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string" } ] } }'{ "funnelId": "cc36c810-1122-4842-933f-6c41b39cda1a", "name": "string", "description": "string", "queryDefinition": { "version": 1, "kind": "funnel", "identity": "session", "counting": "unique", "order": "ordered", "reentry": "first", "windowMs": 1, "steps": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } } ], "entryFilter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } }, "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, "watched": true, "status": "READY", "reportDateRange": { "from": "string", "to": "string" }, "createdAt": "string", "updatedAt": "string"}GET/rest/v1/funnels/{id}
Ours Privacy API key
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/rest/v1/funnels/string"{ "funnelId": "cc36c810-1122-4842-933f-6c41b39cda1a", "name": "string", "description": "string", "queryDefinition": { "version": 1, "kind": "funnel", "identity": "session", "counting": "unique", "order": "ordered", "reentry": "first", "windowMs": 1, "steps": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } } ], "entryFilter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } }, "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, "watched": true, "status": "READY", "reportDateRange": { "from": "string", "to": "string" }, "createdAt": "string", "updatedAt": "string"}PATCH/rest/v1/funnels/{id}
Ours Privacy API key
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/rest/v1/funnels/string" \ -H "Content-Type: application/json" \ -d '{}'{ "funnelId": "cc36c810-1122-4842-933f-6c41b39cda1a", "name": "string", "description": "string", "queryDefinition": { "version": 1, "kind": "funnel", "identity": "session", "counting": "unique", "order": "ordered", "reentry": "first", "windowMs": 1, "steps": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } } ], "entryFilter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } }, "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, "watched": true, "status": "READY", "reportDateRange": { "from": "string", "to": "string" }, "createdAt": "string", "updatedAt": "string"}DELETE/rest/v1/funnels/{id}
Ours Privacy API key
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/rest/v1/funnels/string"{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "deleted": true}POST/rest/v1/funnels/{id}/duplicate
Ours Privacy API key
In: header
Path Parameters
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/rest/v1/funnels/string/duplicate"{ "funnelId": "cc36c810-1122-4842-933f-6c41b39cda1a", "name": "string", "description": "string", "queryDefinition": { "version": 1, "kind": "funnel", "identity": "session", "counting": "unique", "order": "ordered", "reentry": "first", "windowMs": 1, "steps": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "eventName": "string", "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } } ], "entryFilter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } }, "filter": { "version": 1, "filter": { "kind": "and", "children": [ { "kind": "and", "children": [] } ] } } }, "watched": true, "status": "READY", "reportDateRange": { "from": "string", "to": "string" }, "createdAt": "string", "updatedAt": "string"}GET/rest/v1/funnels/{id}/results
Ours Privacy API key
In: header
Path Parameters
Query Parameters
Use the saved funnel response's updatedAt from GET /funnels/{id} (MCP: get_funnel.updatedAt) to require that definition revision. Results return the same revision as definitionUpdatedAt. Returns a conflict if the funnel has changed; omit to use the latest saved definition.
date-timeInclusive lower bound of the analysis window, as a UTC calendar day in YYYY-MM-DD format. The window may span at most 93 days including both endpoints.
^\d{4}-\d{2}-\d{2}$Inclusive upper bound of the analysis window, as a UTC calendar day in YYYY-MM-DD format. Must be on or after from, and the window may span at most 93 days including both endpoints.
^\d{4}-\d{2}-\d{2}$Split results by a property. JSON object {property:{property,path?,type},limit?}. type is string, number or boolean; limit is 1–10 (default 5). Properties come from GET /rest/v1/analytics/query-catalog. Optional stepNumber (default 1) is the step whose event supplies the value; any-order funnels accept only 1. Example: {"property":{"property":"event.properties","path":["plan"],"type":"string"},"stepNumber":2}
Compare with another range of the same length. JSON object {kind,from?}: kind is previous_period, previous_year or custom; custom requires from (YYYY-MM-DD). Example: {"kind":"previous_period"}
Include sample visitor and session IDs; defaults to true.
Results may be served from a recent cache; pass refresh=true to recompute.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/rest/v1/funnels/string/results?from=2026-06-01&to=2026-06-30"{ "definitionUpdatedAt": "2019-08-24T14:15:22Z", "scope": { "timezone": "UTC", "entryFrom": "string", "entryTo": "string", "observationFrom": "string", "observationTo": "string", "windowMs": 1, "watermark": "string", "observationComplete": true, "settledEntryTo": "string" }, "semanticVersion": 1, "sourcePolicy": "events-v3-physical-key", "sourceRevision": "string", "sourceLimitations": [ "equal-load-conflicts-unverified" ], "engine": "string", "steps": [ { "stepNumber": 0, "visitorCount": 0, "conversionCount": 0, "conversionRate": 0, "dropOffRate": 0, "overallConversionRate": 0, "avgTimeToNextStep": 0, "sessionIds": [ "string" ], "dropOffSessionIds": [ "string" ], "visitorIds": [ "string" ], "dropOffVisitorIds": [ "string" ] } ], "totalVisitors": 0, "overallConversionRate": 0, "overallAvgTimeToConversion": 0, "breakdown": { "scope": { "property": { "property": "string", "path": [ "string" ], "type": "string" }, "limit": 0, "valueCount": 0, "truncated": true, "stepNumber": 0, "atAnchorId": "string" }, "segments": [ { "segment": { "key": "string", "kind": "value", "value": "string", "label": "string", "rank": 0 }, "totalVisitors": 0, "overallConversionRate": 0, "overallAvgTimeToConversion": 0, "steps": [ { "stepNumber": 0, "visitorCount": 0, "conversionCount": 0, "conversionRate": 0, "dropOffRate": 0, "overallConversionRate": 0, "avgTimeToNextStep": 0, "sessionIds": [ "string" ], "dropOffSessionIds": [ "string" ], "visitorIds": [ "string" ], "dropOffVisitorIds": [ "string" ] } ] } ] }, "comparison": { "scope": { "kind": "previous_period", "from": "2019-08-24", "to": "2019-08-24" }, "totalVisitors": 0, "overallConversionRate": 0, "overallAvgTimeToConversion": 0, "steps": [ { "stepNumber": 0, "visitorCount": 0, "conversionCount": 0, "conversionRate": 0, "dropOffRate": 0, "overallConversionRate": 0, "avgTimeToNextStep": 0, "sessionIds": [ "string" ], "dropOffSessionIds": [ "string" ], "visitorIds": [ "string" ], "dropOffVisitorIds": [ "string" ] } ], "segments": [ { "segment": { "key": "string", "kind": "value", "value": "string", "label": "string", "rank": 0 }, "totalVisitors": 0, "overallConversionRate": 0, "overallAvgTimeToConversion": 0, "steps": [ { "stepNumber": 0, "visitorCount": 0, "conversionCount": 0, "conversionRate": 0, "dropOffRate": 0, "overallConversionRate": 0, "avgTimeToNextStep": 0, "sessionIds": [ "string" ], "dropOffSessionIds": [ "string" ], "visitorIds": [ "string" ], "dropOffVisitorIds": [ "string" ] } ] } ] }}Next Steps
How is this guide?

