Funnels

The Funnels API lets you define multi-step conversion funnels and analyze drop-off rates across date ranges.

All endpoints require an OAuth 2.0 Bearer token with the appropriate scope.

List Funnels

Retrieve all funnel definitions for your organization.

GET /v1/funnels

Authentication: OAuth Bearer

Scope: insightcore:funnels.read

Rate Limit: 100/min

Response

{
  "data": [
    {
      "funnel_id": "fnl_00000k1L2m3N4o5",
      "organization_id": "org_00000a1B2c3D4e5",
      "name": "Checkout Funnel",
      "steps": [
        { "name": "Product View", "event_type": "product_view" },
        { "name": "Add to Cart", "event_type": "add_to_cart" },
        { "name": "Checkout", "event_type": "checkout" },
        { "name": "Purchase", "event_type": "purchase" }
      ],
      "is_active": true,
      "created_at": "2026-03-26T12:00:00Z",
      "updated_at": "2026-03-26T12:00:00Z"
    }
  ]
}

Create Funnel

Define a new conversion funnel.

POST /v1/funnels

Authentication: OAuth Bearer

Scope: insightcore:funnels.write

Rate Limit: 100/min

Request Body

{
  "name": "Checkout Funnel",
  "steps": [
    { "name": "Product View", "event_type": "product_view" },
    { "name": "Add to Cart", "event_type": "add_to_cart" },
    { "name": "Checkout", "event_type": "checkout" },
    { "name": "Purchase", "event_type": "purchase" }
  ]
}

Request Fields

Field	Type	Required	Description
name	string	Yes	Funnel display name (max 100 characters)
steps	array	Yes	Ordered list of funnel steps (minimum 2)
steps[].name	string	Yes	Step display name (max 100 characters)
steps[].event_type	string	Yes	Event type that triggers this step (max 50 characters)
steps[].event_name	string	No	Optional event name filter (max 100 characters)

Response

201 Created:

{
  "data": {
    "funnel_id": "fnl_00000k1L2m3N4o5",
    "organization_id": "org_00000a1B2c3D4e5",
    "name": "Checkout Funnel",
    "steps": [
      { "name": "Product View", "event_type": "product_view" },
      { "name": "Add to Cart", "event_type": "add_to_cart" },
      { "name": "Checkout", "event_type": "checkout" },
      { "name": "Purchase", "event_type": "purchase" }
    ],
    "is_active": true,
    "created_at": "2026-03-26T12:00:00Z",
    "updated_at": "2026-03-26T12:00:00Z"
  }
}

Get Funnel

Retrieve a single funnel definition.

GET /v1/funnels/{funnel_id}

Authentication: OAuth Bearer

Scope: insightcore:funnels.read

Path Parameters

Parameter	Type	Description
funnel_id	string	Funnel identifier (e.g., fnl_00000k1L2m3N4o5)

Response

{
  "data": {
    "funnel_id": "fnl_00000k1L2m3N4o5",
    "organization_id": "org_00000a1B2c3D4e5",
    "name": "Checkout Funnel",
    "steps": [
      { "name": "Product View", "event_type": "product_view" },
      { "name": "Add to Cart", "event_type": "add_to_cart" },
      { "name": "Checkout", "event_type": "checkout" },
      { "name": "Purchase", "event_type": "purchase" }
    ],
    "is_active": true,
    "created_at": "2026-03-26T12:00:00Z",
    "updated_at": "2026-03-26T12:00:00Z"
  }
}

Update Funnel

Update an existing funnel definition.

PUT /v1/funnels/{funnel_id}

Authentication: OAuth Bearer

Scope: insightcore:funnels.write

Path Parameters

Parameter	Type	Description
funnel_id	string	Funnel identifier

Request Body

All fields are optional. Only provided fields are updated.

{
  "name": "Updated Checkout Funnel",
  "steps": [
    { "name": "Browse", "event_type": "page_view" },
    { "name": "Product View", "event_type": "product_view" },
    { "name": "Add to Cart", "event_type": "add_to_cart" },
    { "name": "Purchase", "event_type": "purchase" }
  ],
  "is_active": true
}

Request Fields

Field	Type	Required	Description
name	string	No	Updated funnel name
steps	array	No	Replacement step list (minimum 2 if provided)
is_active	boolean	No	Enable or disable the funnel

Response

200 OK:

{
  "data": {
    "funnel_id": "fnl_00000k1L2m3N4o5",
    "name": "Updated Checkout Funnel",
    "steps": [ ... ],
    "is_active": true,
    "updated_at": "2026-03-26T14:30:00Z"
  }
}

Delete Funnel

Soft-delete a funnel definition. Historical analysis data is retained.

DELETE /v1/funnels/{funnel_id}

Authentication: OAuth Bearer

Scope: insightcore:funnels.write

Path Parameters

Parameter	Type	Description
funnel_id	string	Funnel identifier

Response

204 No Content

Analyze Funnel

Retrieve funnel analysis for a date range, showing entries, exits, and completion rates at each step.

GET /v1/funnels/{funnel_id}/analyze

Authentication: OAuth Bearer

Scope: insightcore:funnels.read

Rate Limit: 100/min

Path Parameters

Parameter	Type	Description
funnel_id	string	Funnel identifier

Query Parameters

Parameter	Type	Required	Description
from	string	Yes	Start date (ISO 8601, e.g., 2026-03-01)
to	string	Yes	End date (ISO 8601, e.g., 2026-03-26)

Response

{
  "data": {
    "funnel_id": "fnl_00000k1L2m3N4o5",
    "name": "Checkout Funnel",
    "period": {
      "from": "2026-03-01",
      "to": "2026-03-26"
    },
    "steps": [
      {
        "step_number": 1,
        "step_name": "Product View",
        "event_type": "product_view",
        "entries": 12450,
        "exits": 8200,
        "completion_rate": 0.3414
      },
      {
        "step_number": 2,
        "step_name": "Add to Cart",
        "event_type": "add_to_cart",
        "entries": 4250,
        "exits": 2100,
        "completion_rate": 0.5059
      },
      {
        "step_number": 3,
        "step_name": "Checkout",
        "event_type": "checkout",
        "entries": 2150,
        "exits": 650,
        "completion_rate": 0.6977
      },
      {
        "step_number": 4,
        "step_name": "Purchase",
        "event_type": "purchase",
        "entries": 1500,
        "exits": 0,
        "completion_rate": 1.0
      }
    ]
  }
}

Response Fields

Field	Type	Description
steps[].step_number	integer	Position in the funnel (1-indexed)
steps[].step_name	string	Display name for this step
steps[].event_type	string	Event type that triggers this step
steps[].entries	integer	Number of visitors who reached this step
steps[].exits	integer	Number of visitors who left at this step
steps[].completion_rate	number	Fraction of entries that progressed to the next step (0.0–1.0)

---

Changelog

Date	Change
2026-03-26	Initial publication.