CDPGuidesSupport

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

GET
/rest/v1/funnels
AuthorizationBearer <token>

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

POST
/rest/v1/funnels
*object
object
AuthorizationBearer <token>

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}

GET
/rest/v1/funnels/{id}
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

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}

PATCH
/rest/v1/funnels/{id}
*object
object
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

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}

DELETE
/rest/v1/funnels/{id}
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

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

POST
/rest/v1/funnels/{id}/duplicate
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

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

GET
/rest/v1/funnels/{id}/results
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

expectedDefinitionUpdatedAt?string

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.

Formatdate-time
from*string

Inclusive 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.

Match^\d{4}-\d{2}-\d{2}$
to*string

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.

Match^\d{4}-\d{2}-\d{2}$
breakdown?string

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}

comparison?string

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"}

includeSamples?boolean

Include sample visitor and session IDs; defaults to true.

refresh?boolean

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?