Funnel

For instructions on how to authenticate to use this endpoint, see API overview.

Create

Required API key scopes

insight:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • events
    Click to open
    array

    Events to filter on. One of events or actions is required.

  • actions
    Click to open
    array

    Actions to filter on. One of events or actions is required.

  • properties

    Filter events by event property, person property, cohort, groups and more.

  • filter_test_accounts
    boolean

    Whether to filter out internal and test accounts. See "project settings" in your PostHog account for the filters.

  • date_from
    string
    Default: -7d

    What date to filter the results from. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

  • date_to
    string
    Default: -7d

    What date to filter the results to. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

  • breakdown
    string

    A property or cohort to break down on. You can select the type of the property with breakdown_type.

    • event (default): a property key
    • person: a person property key
    • cohort: an array of cohort IDs (ie [9581,5812])
  • breakdown_type
    Default: event

    Type of property to break down on.

    • event - event
    • person - person
    • cohort - cohort
    • group - group
    • session - session
    • hogql - hogql
  • funnel_window_interval
    integer
    Default: 14

    Funnel window size. Set in combination with funnel_window_interval, so defaults to 'days'.

  • funnel_window_interval_type
    Default: days

    The type of interval. Used in combination with funnel_window_intervals.

    • DAY - DAY
    • SECOND - SECOND
    • MINUTE - MINUTE
    • HOUR - HOUR
    • WEEK - WEEK
    • MONTH - MONTH
  • funnel_viz_type
    Default: steps

    The visualisation type.

    • steps Track instances progress between steps of the funnel
    • trends Track how this funnel's conversion rate is trending over time.
    • time_to_convert Track how long it takes for instances to convert
    • trends - trends
    • time_to_convert - time_to_convert
    • steps - steps
  • funnel_order_type
    Default: ordered
    • ordered - Step B must happen after Step A, but any number events can happen between A and B.
    • strict - Step B must happen directly after Step A without any events in between.
    • unordered - Steps can be completed in any sequence.
    • strict - strict
    • unordered - unordered
    • ordered - ordered
  • exclusions
    Click to open
    array

    Exclude users/groups that completed the specified event between two specific steps. Note that these users/groups will be completely excluded from the entire funnel.

  • aggregation_group_type_index
    integer
    0

    Aggregate by users or by groups. 0 means user, >0 means a group. See interface for the corresponding ID of the group.

  • breakdown_limit
    integer
    Default: 10
  • funnel_window_days
    integer
    Default: 14

    (DEPRECATED) Funnel window size in days. Use funnel_window_interval and funnel_window_interval_type

Response


Request

POST /api/environments/:project_id/insights/funnel
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/insights/funnel/\
	-d events=[{"id":"$pageview"}]

Response

Status 200 Note, if funnel_viz_type is set the response will be different.
RESPONSE
{
  "is_cached": true,
  "last_refresh": "2019-08-24T14:15:22Z",
  "timezone": "UTC",
  "result": [
    {
      "count": 0,
      "action_id": "string",
      "average_conversion_time": 0,
      "median_conversion_time": 0,
      "converted_people_url": "string",
      "dropped_people_url": "string",
      "order": "string"
    }
  ]
}

Create funnels

Required API key scopes

insight:read

Path parameters

  • project_id
    string

    Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Query parameters

  • format
    string
    One of: "csv""json"

Request parameters

  • events
    Click to open
    array

    Events to filter on. One of events or actions is required.

  • actions
    Click to open
    array

    Actions to filter on. One of events or actions is required.

  • properties

    Filter events by event property, person property, cohort, groups and more.

  • filter_test_accounts
    boolean

    Whether to filter out internal and test accounts. See "project settings" in your PostHog account for the filters.

  • date_from
    string
    Default: -7d

    What date to filter the results from. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

  • date_to
    string
    Default: -7d

    What date to filter the results to. Can either be a date 2021-01-01, or a relative date, like -7d for last seven days, -1m for last month, mStart for start of the month or yStart for the start of the year.

  • breakdown
    string

    A property or cohort to break down on. You can select the type of the property with breakdown_type.

    • event (default): a property key
    • person: a person property key
    • cohort: an array of cohort IDs (ie [9581,5812])
  • breakdown_type
    Default: event

    Type of property to break down on.

    • event - event
    • person - person
    • cohort - cohort
    • group - group
    • session - session
    • hogql - hogql
  • funnel_window_interval
    integer
    Default: 14

    Funnel window size. Set in combination with funnel_window_interval, so defaults to 'days'.

  • funnel_window_interval_type
    Default: days

    The type of interval. Used in combination with funnel_window_intervals.

    • DAY - DAY
    • SECOND - SECOND
    • MINUTE - MINUTE
    • HOUR - HOUR
    • WEEK - WEEK
    • MONTH - MONTH
  • funnel_viz_type
    Default: steps

    The visualisation type.

    • steps Track instances progress between steps of the funnel
    • trends Track how this funnel's conversion rate is trending over time.
    • time_to_convert Track how long it takes for instances to convert
    • trends - trends
    • time_to_convert - time_to_convert
    • steps - steps
  • funnel_order_type
    Default: ordered
    • ordered - Step B must happen after Step A, but any number events can happen between A and B.
    • strict - Step B must happen directly after Step A without any events in between.
    • unordered - Steps can be completed in any sequence.
    • strict - strict
    • unordered - unordered
    • ordered - ordered
  • exclusions
    Click to open
    array

    Exclude users/groups that completed the specified event between two specific steps. Note that these users/groups will be completely excluded from the entire funnel.

  • aggregation_group_type_index
    integer
    0

    Aggregate by users or by groups. 0 means user, >0 means a group. See interface for the corresponding ID of the group.

  • breakdown_limit
    integer
    Default: 10
  • funnel_window_days
    integer
    Default: 14

    (DEPRECATED) Funnel window size in days. Use funnel_window_interval and funnel_window_interval_type

Response


Request

POST /api/projects/:project_id/insights/funnel
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/insights/funnel/\
	-d events=[{"id":"$pageview"}]

Response

Status 200 Note, if funnel_viz_type is set the response will be different.
RESPONSE
{
  "is_cached": true,
  "last_refresh": "2019-08-24T14:15:22Z",
  "timezone": "UTC",
  "result": [
    {
      "count": 0,
      "action_id": "string",
      "average_conversion_time": 0,
      "median_conversion_time": 0,
      "converted_people_url": "string",
      "dropped_people_url": "string",
      "order": "string"
    }
  ]
}

Questions?

Was this page useful?