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.

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 91 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 91 days including both endpoints.

Match^\d{4}-\d{2}-\d{2}$

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}

How is this guide?