Insights API Reference

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, how aggresively, and if sync or async:
- 'force_cache' - return cached data or a cache miss; always completes immediately as it never calculates
- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache
- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache
- 'lazy_async' - kick off background calculation, UNLESS there are somewhat fresh results in the cache
- 'force_blocking' - calculate synchronously, even if fresh results are already cached
- 'force_async' - kick off background calculation, even if fresh results are already cached 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"
}

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, how aggresively, and if sync or async:
- 'force_cache' - return cached data or a cache miss; always completes immediately as it never calculates
- 'blocking' - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache
- 'async' - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache
- 'lazy_async' - kick off background calculation, UNLESS there are somewhat fresh results in the cache
- 'force_blocking' - calculate synchronously, even if fresh results are already cached
- 'force_async' - kick off background calculation, even if fresh results are already cached 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
array
Events to filter on. One of events or actions is required.
actions
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
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
array
Events to filter on. One of events or actions is required.
actions
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"
    }
  ]
}

Insights

Endpoints

List all insights

Required API key scopes

Path parameters

Query parameters

Response

Request

Response

Status 200

Create insights

Required API key scopes

Path parameters

Query parameters

Request parameters

Response

Request

Response

Status 201

List all insights sharing

Required API key scopes

Path parameters

Request

Response

Status 200

Retrieve insights

Required API key scopes

Path parameters

Query parameters

Response

Request

Response

Status 200

Update insights

Required API key scopes

Path parameters

Query parameters

Request parameters

Response

Request

Response

Status 200

Delete insights

Required API key scopes

Path parameters

Query parameters

Request

Response

Status 405 No response body

Retrieve insights activity retrieve

Required API key scopes

Path parameters

Query parameters

Request

Response

Status 200 No response body

Create insights viewed

Path parameters

Query parameters

Request parameters

Request

Response

Status 200 No response body

Retrieve insights activity

Required API key scopes

Path parameters

Query parameters

Request

Response

Status 200 No response body

Create insights cancel

Path parameters

Query parameters

Request parameters

Request

Response

Status 200 No response body

Retrieve insights funnel

Required API key scopes

Path parameters