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/:insight_id/sharing/
    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/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

    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

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

    • refresh
      string
      Default: force_cache
      One of: "async""blocking""force_async""force_blocking""force_cache""lazy_async"

      Whether to refresh the retrieved insights and how aggressively. (The default force_cache value never refreshes.) If an _async mode is chosen, this request kicks off a background query and returns immediately. Background calculation can be tracked using the query_status response field.

    • 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" \
    <ph_app_host>/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": null,
    "query": null,
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "dashboard_tiles": [
    {
    "id": 0,
    "dashboard_id": 0,
    "deleted": true
    }
    ],
    "last_refresh": "string",
    "cache_target_age": "string",
    "next_allowed_client_refresh": "string",
    "result": "string",
    "hasMore": "string",
    "columns": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "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",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string",
    "is_cached": "string",
    "query_status": "string",
    "hogql": "string",
    "types": "string"
    }
    ]
    }

    Create insights

    Required API key scopes

    insight:write

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

      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" \
    <ph_app_host>/api/projects/:project_id/insights/\
    -d name="string"

    Response

    Status 201
    RESPONSE
    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": null,
    "query": null,
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "dashboard_tiles": [
    {
    "id": 0,
    "dashboard_id": 0,
    "deleted": true
    }
    ],
    "last_refresh": "string",
    "cache_target_age": "string",
    "next_allowed_client_refresh": "string",
    "result": "string",
    "hasMore": "string",
    "columns": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "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",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string",
    "is_cached": "string",
    "query_status": "string",
    "hogql": "string",
    "types": "string"
    }

    List all insights sharing

    Required API key scopes

    sharing_configuration:read

    Path parameters

    • insight_id
      integer
    • 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/.

    Request

    GET /api/projects/:project_id/insights/:insight_id/sharing
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/insights/:insight_id/sharing/

    Response

    Status 200
    RESPONSE
    {
    "created_at": "2019-08-24T14:15:22Z",
    "enabled": true,
    "access_token": "string"
    }

    Retrieve insights

    Required API key scopes

    insight:read

    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

      Only if loading an insight in the context of a dashboard: The relevant dashboard's ID. When set, the specified dashboard's filters and date range override will be applied.

    • refresh
      string
      Default: force_cache
      One of: "async""blocking""force_async""force_blocking""force_cache""lazy_async"

      Whether to refresh the insight and how aggressively. (The default force_cache value never refreshes.) If an _async mode is chosen, this request kicks off a background query and returns immediately. Background calculation can be tracked using the query_status response field.

    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" \
    <ph_app_host>/api/projects/:project_id/insights/:id/

    Response

    Status 200
    RESPONSE
    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": null,
    "query": null,
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "dashboard_tiles": [
    {
    "id": 0,
    "dashboard_id": 0,
    "deleted": true
    }
    ],
    "last_refresh": "string",
    "cache_target_age": "string",
    "next_allowed_client_refresh": "string",
    "result": "string",
    "hasMore": "string",
    "columns": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "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",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string",
    "is_cached": "string",
    "query_status": "string",
    "hogql": "string",
    "types": "string"
    }

    Update insights

    Required API key scopes

    insight:write

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

      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" \
    <ph_app_host>/api/projects/:project_id/insights/:id/\
    -d name="string"

    Response

    Status 200
    RESPONSE
    {
    "id": 0,
    "short_id": "string",
    "name": "string",
    "derived_name": "string",
    "filters": null,
    "query": null,
    "order": -2147483648,
    "deleted": true,
    "dashboards": [
    0
    ],
    "dashboard_tiles": [
    {
    "id": 0,
    "dashboard_id": 0,
    "deleted": true
    }
    ],
    "last_refresh": "string",
    "cache_target_age": "string",
    "next_allowed_client_refresh": "string",
    "result": "string",
    "hasMore": "string",
    "columns": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "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",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {
    "property1": null,
    "property2": null
    }
    },
    "is_sample": true,
    "effective_restriction_level": 21,
    "effective_privilege_level": 21,
    "timezone": "string",
    "is_cached": "string",
    "query_status": "string",
    "hogql": "string",
    "types": "string"
    }

    Delete insights

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

    Required API key scopes

    insight:write

    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" \
    <ph_app_host>/api/projects/:project_id/insights/:id/

    Response

    Status 405 No response body

    Retrieve insights activity retrieve

    Required API key scopes

    activity_log:read

    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

    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" \
    <ph_app_host>/api/projects/:project_id/insights/:id/activity/

    Response

    Status 200 No response body

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

      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

    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" \
    <ph_app_host>/api/projects/:project_id/insights/:id/viewed/\
    -d name="string"

    Response

    Status 200 No response body

    Retrieve insights activity

    Required API key scopes

    activity_log: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

    GET /api/projects/:project_id/insights/activity
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/insights/activity/

    Response

    Status 200 No response body

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

      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

    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" \
    <ph_app_host>/api/projects/:project_id/insights/cancel/\
    -d name="string"

    Response

    Status 200 No response body

    Retrieve insights funnel

    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

    GET /api/projects/:project_id/insights/funnel
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/insights/funnel/

    Response

    Status 200 No response body

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

    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"

    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" \
    <ph_app_host>/api/projects/:project_id/insights/funnel/correlation/

    Response

    Status 200 No response body

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

      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

    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" \
    <ph_app_host>/api/projects/:project_id/insights/funnel/correlation/\
    -d name="string"

    Response

    Status 200 No response body

    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"

    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" \
    <ph_app_host>/api/projects/:project_id/insights/my_last_viewed/

    Response

    Status 200 No response body

    Retrieve insights path

    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

    GET /api/projects/:project_id/insights/path
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/insights/path/

    Response

    Status 200 No response body

    Create insights path

    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

    • name
      string
    • derived_name
      string
    • filters
    • query

      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

    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" \
    <ph_app_host>/api/projects/:project_id/insights/path/\
    -d name="string"

    Response

    Status 200 No response body

    Retrieve insights retention

    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

    GET /api/projects/:project_id/insights/retention
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/insights/retention/

    Response

    Status 200 No response body

    Create insights retention

    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

    • name
      string
    • derived_name
      string
    • filters
    • query

      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

    Request

    POST /api/projects/:project_id/insights/retention
    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/retention/\
    -d name="string"

    Response

    Status 200 No response body

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

      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

    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" \
    <ph_app_host>/api/projects/:project_id/insights/timing/\
    -d name="string"

    Response

    Status 200 No response body

    Retrieve insights trend

    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

    GET /api/projects/:project_id/insights/trend
    export POSTHOG_PERSONAL_API_KEY=[your personal api key]
    curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/insights/trend/

    Response

    Status 200 No response body

    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
    • compare
      boolean

      To compare or not

    • compare_to
      string

      What to compare to

    • display
      Default: ActionsLineGraph

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

      • ActionsLineGraph - ActionsLineGraph
      • ActionsLineGraphCumulative - ActionsLineGraphCumulative
      • ActionsTable - ActionsTable
      • ActionsPie - ActionsPie
      • ActionsBar - ActionsBar
      • ActionsBarValue - ActionsBarValue
      • WorldMap - WorldMap
      • BoldNumber - BoldNumber
    • 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.

    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" \
    <ph_app_host>/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": "UTC",
    "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?