Insights API Reference

Insights

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

Adds an "access_controls" action to the viewset that handles access control for the given resource

Why a mixin? We want to easily add this to any existing resource, including providing easy helpers for adding access control info such as the current users access level to any response.

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/`
`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""async_except_on_cache_miss""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
        },
        "role_at_organization": "engineering"
      },
      "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
        },
        "role_at_organization": "engineering"
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "user_access_level": "string",
      "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
    },
    "role_at_organization": "engineering"
  },
  "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
    },
    "role_at_organization": "engineering"
  },
  "is_sample": true,
  "effective_restriction_level": 21,
  "effective_privilege_level": 21,
  "user_access_level": "string",
  "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""async_except_on_cache_miss""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
    },
    "role_at_organization": "engineering"
  },
  "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
    },
    "role_at_organization": "engineering"
  },
  "is_sample": true,
  "effective_restriction_level": 21,
  "effective_privilege_level": 21,
  "user_access_level": "string",
  "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
    },
    "role_at_organization": "engineering"
  },
  "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
    },
    "role_at_organization": "engineering"
  },
  "is_sample": true,
  "effective_restriction_level": 21,
  "effective_privilege_level": 21,
  "user_access_level": "string",
  "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

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"

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

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 name="string"

Response

Status 200 No response body

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

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 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 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/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 name="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

Required API key scopes

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