Insights

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

Endpoints

    GET/api/projects/:project_id/insights/
    POST/api/projects/:project_id/insights/
    GET/api/projects/:project_id/insights/:id/
    PATCH/api/projects/:project_id/insights/:id/
    DELETE/api/projects/:project_id/insights/:id/
    GET/api/projects/:project_id/insights/:id/activity/
    POST/api/projects/:project_id/insights/:id/viewed/
    GET/api/projects/:project_id/insights/activity/
    POST/api/projects/:project_id/insights/cancel/
    GET/api/projects/:project_id/insights/funnel/
    POST/api/projects/:project_id/insights/funnel/
    GET/api/projects/:project_id/insights/funnel/correlation/
    POST/api/projects/:project_id/insights/funnel/correlation/
    GET/api/projects/:project_id/insights/my_last_viewed/
    GET/api/projects/:project_id/insights/path/
    POST/api/projects/:project_id/insights/path/
    GET/api/projects/:project_id/insights/retention/
    POST/api/projects/:project_id/insights/timing/
    GET/api/projects/:project_id/insights/trend/
    POST/api/projects/:project_id/insights/trend/

    List all insights

    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

    • created_by
      integer
    • format
      string
      One of: "csv""json"
    • limit
      integer

      Number of results to return per page.

    • offset
      integer

      The initial index from which to return the results.

    • short_id
      string

    Response


    Request

    GET /api/projects/:project_id/insights
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/

    Response

    Status 200
    RESPONSE
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "id": 0,
          "short_id": "string",
          "name": "string",
          "derived_name": "string",
          "filters": {
            "property1": null,
            "property2": null
          },
          "query": {
            "property1": null,
            "property2": null
          },
          "order": -2147483648,
          "deleted": true,
          "dashboards": [
            0
          ],
          "dashboard_tiles": [
            {
              "id": 0,
              "dashboard_id": 0,
              "deleted": true
            }
          ],
          "last_refresh": "string",
          "next_allowed_client_refresh": "string",
          "result": "string",
          "created_at": "2019-08-24T14:15:22Z",
          "created_by": {
            "id": 0,
            "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
            "distinct_id": "string",
            "first_name": "string",
            "email": "user@example.com",
            "is_email_verified": true
          },
          "description": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "tags": [
            null
          ],
          "favorited": true,
          "saved": true,
          "last_modified_at": "2019-08-24T14:15:22Z",
          "last_modified_by": {
            "id": 0,
            "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
            "distinct_id": "string",
            "first_name": "string",
            "email": "user@example.com",
            "is_email_verified": true
          },
          "is_sample": true,
          "effective_restriction_level": 21,
          "effective_privilege_level": 21,
          "timezone": "string",
          "is_cached": "string"
        }
      ]
    }

    Create insights

    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

    • name
      string
    • derived_name
      string
    • filters
      object
    • query
      object

      Query node JSON string

    • order
      integer
    • deleted
      boolean
    • dashboards
      array
          DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/\
    	-d name="string"

    Response

    Status 201
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Retrieve insights

    Path Parameters

    • id
      integer

      A unique integer value identifying this insight.

    • 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"
    • from_dashboard
      integer

      When loading an insight for a dashboard pass a from_dashboard query parameter containing the dashboard ID

      e.g. "/api/projects/{team_id}/insights/{insight_id}?from_dashboard={dashboard_id}"

      Insights can be added to more than one dashboard, this allows the insight to be loaded in the correct context.

      Using the correct cache and enriching the response with dashboard specific config (e.g. layouts or colors)

    • refresh
      boolean
                  The client can request that an insight be refreshed by setting the `refresh=true` parameter.
            The server will then decide if the data should or not be refreshed based on a set of heuristics
            meant to determine the staleness of cached data. The result will contain as `is_cached` field
            that indicates whether the insight was actually refreshed or not through the request.

    Response


    Request

    GET /api/projects/:project_id/insights/:id
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/:id/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Update insights

    Path Parameters

    • id
      integer

      A unique integer value identifying this insight.

    • 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

    • name
      string
    • derived_name
      string
    • filters
      object
    • query
      object

      Query node JSON string

    • order
      integer
    • deleted
      boolean
    • dashboards
      array
          DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    PATCH /api/projects/:project_id/insights/:id
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl -X PATCH \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/:id/\
    	-d name="string"

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Delete insights

    Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true

    Path Parameters

    • id
      integer

      A unique integer value identifying this insight.

    • 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

    DELETE /api/projects/:project_id/insights/:id
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl  -X DELETE \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/:id/

    Response

    Status 405 No response body

    Retrieve insights activity retrieve

    Path Parameters

    • id
      integer

      A unique integer value identifying this insight.

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

    Response


    Request

    GET /api/projects/:project_id/insights/:id/activity
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/:id/activity/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Create insights viewed

    Path Parameters

    • id
      integer

      A unique integer value identifying this insight.

    • 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

    • name
      string
    • derived_name
      string
    • filters
      object
    • query
      object

      Query node JSON string

    • order
      integer
    • deleted
      boolean
    • dashboards
      array
          DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/:id/viewed
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/:id/viewed/\
    	-d name="string"

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Retrieve insights activity

    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"

    Response


    Request

    GET /api/projects/:project_id/insights/activity
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/activity/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Create insights cancel

    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

    • name
      string
    • derived_name
      string
    • filters
      object
    • query
      object

      Query node JSON string

    • order
      integer
    • deleted
      boolean
    • dashboards
      array
          DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/cancel
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/cancel/\
    	-d name="string"

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Retrieve insights funnel

    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"

    Response


    Request

    GET /api/projects/:project_id/insights/funnel
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/funnel/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Create

    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
      string
      Default: event
      One of: "event""person""cohort""group""session""hogql"

      Type of property to break down on.

    • funnel_window_interval
      integer
      Default: 14

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

    • funnel_window_interval_type
      string
      Default: days
      One of: "DAY""SECOND""MINUTE""HOUR""WEEK""MONTH"

      The type of interval. Used in combination with funnel_window_intervals.

    • funnel_viz_type
      string
      Default: steps
      One of: "trends""time_to_convert""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
    • funnel_order_type
      string
      Default: ordered
      One of: "strict""unordered""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.
    • 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" \
        https://app.posthog.com/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": "Africa/Abidjan",
      "result": [
        {
          "count": 0,
          "action_id": "string",
          "average_conversion_time": 0,
          "median_conversion_time": 0,
          "converted_people_url": "string",
          "dropped_people_url": "string",
          "order": "string"
        }
      ]
    }

    Retrieve insights funnel correlation

    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"

    Response


    Request

    GET /api/projects/:project_id/insights/funnel/correlation
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/funnel/correlation/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Create insights funnel correlation

    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

    • name
      string
    • derived_name
      string
    • filters
      object
    • query
      object

      Query node JSON string

    • order
      integer
    • deleted
      boolean
    • dashboards
      array
          DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/funnel/correlation
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/funnel/correlation/\
    	-d name="string"

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Retrieve insights my last viewed

    Returns basic details about the last 5 insights viewed by this user. Most recently viewed first.

    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"

    Response


    Request

    GET /api/projects/:project_id/insights/my_last_viewed
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/my_last_viewed/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Retrieve insights path

    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"

    Response


    Request

    GET /api/projects/:project_id/insights/path
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/path/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Create insights path

    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

    • name
      string
    • derived_name
      string
    • filters
      object
    • query
      object

      Query node JSON string

    • order
      integer
    • deleted
      boolean
    • dashboards
      array
          DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/path
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/path/\
    	-d name="string"

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Retrieve insights retention

    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"

    Response


    Request

    GET /api/projects/:project_id/insights/retention
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/retention/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Create insights timing

    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

    • name
      string
    • derived_name
      string
    • filters
      object
    • query
      object

      Query node JSON string

    • order
      integer
    • deleted
      boolean
    • dashboards
      array
          DEPRECATED. Will be removed in a future release. Use dashboard_tiles instead.
    A dashboard ID for each of the dashboards that this insight is displayed on.
    • description
      string
    • tags
      array
    • favorited
      boolean
    • saved
      boolean

    Response


    Request

    POST /api/projects/:project_id/insights/timing
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/timing/\
    	-d name="string"

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Retrieve insights trend

    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"

    Response


    Request

    GET /api/projects/:project_id/insights/trend
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/trend/

    Response

    Status 200
    RESPONSE
    {
      "id": 0,
      "short_id": "string",
      "name": "string",
      "derived_name": "string",
      "filters": {
        "property1": null,
        "property2": null
      },
      "query": {
        "property1": null,
        "property2": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "string",
      "next_allowed_client_refresh": "string",
      "result": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": true,
      "saved": true,
      "last_modified_at": "2019-08-24T14:15:22Z",
      "last_modified_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "email": "user@example.com",
        "is_email_verified": true
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "timezone": "string",
      "is_cached": "string"
    }

    Create

    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
      string
      Default: event
      One of: "event""person""cohort""group""session""hogql"

      Type of property to break down on.

    • display
      string
      Default: ActionsLineGraph
      One of: "ActionsLineGraph""ActionsLineGraphCumulative""ActionsTable""ActionsPie""ActionsBar""ActionsBarValue""WorldMap""BoldNumber"

      How to display the data. Will change how the data is returned.

    • formula
      string

      Combine the result of events or actions into a single number. For example A + B or (A-B)/B. The letters correspond to the order of the events or actions lists.

    • compare
      boolean

      For each returned result show the current period and the previous period. The result will contain compare:true and a compare_label with either current or previous.

    Response


    Request

    POST /api/projects/:project_id/insights/trend
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl 
        -H 'Content-Type: application/json'\
        -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
        https://app.posthog.com/api/projects/:project_id/insights/trend/\
    	-d events=[{"id":"$pageview"}]

    Response

    Status 200
    RESPONSE
    {
      "is_cached": true,
      "last_refresh": "2019-08-24T14:15:22Z",
      "timezone": "Africa/Abidjan",
      "result": [
        {
          "data": [
            0
          ],
          "days": [
            "2019-08-24"
          ],
          "labels": [
            "string"
          ],
          "filter": {
            "events": [
              {
                "id": "string",
                "properties": [
                  {
                    "type": "AND",
                    "values": [
                      {
                        "key": "string",
                        "value": "string",
                        "operator": "exact",
                        "type": "event"
                      }
                    ]
                  }
                ],
                "math": "total"
              }
            ],
            "actions": [
              {
                "id": "string",
                "properties": [
                  {
                    "type": "AND",
                    "values": [
                      {
                        "key": "string",
                        "value": "string",
                        "operator": "exact",
                        "type": "event"
                      }
                    ]
                  }
                ],
                "math": "total"
              }
            ],
            "properties": {
              "type": "AND",
              "values": [
                {
                  "key": "string",
                  "value": "string",
                  "operator": "exact",
                  "type": "event"
                }
              ]
            },
            "filter_test_accounts": false,
            "date_from": "-7d",
            "date_to": "-7d"
          },
          "label": "string"
        }
      ]
    }

    Questions?

    Was this page useful?