Insights

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

Endpoints

POST
POST
GET
GET
POST
← Previous page

Create insights data checks

Check the events behind an insight for the common ways they mislead: local development traffic, bots and crawlers, and events sent twice. Works for trends, funnels, stickiness and lifecycle insights whose series are events. The checks apply the insight's own filters, and read the newest days of its date range, up to 7. The bot and duplicate checks read a sample of those days. Nothing is stored. This route runs the query it is sent, so it needs query access as well as insight access. To check a saved insight by its id, send a GET request to insights/{id}/data_checks/.

Required API key scopes

insight:readquery:read

Query parameters

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

Request parameters

  • query

Response


Example request

POST /api/projects/:project_id/insights/data_checks
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/data_checks/\
	-d query=undefined

Example response

Status 200 The result of every check.
RESPONSE
{
  "status": "passed",
  "checks": [
    {
      "key": "local_development",
      "level": "passed",
      "skip_reason": "too_many_events",
      "method": "counted",
      "events": 0,
      "share": 0,
      "scaled": true,
      "action": "open_filter_settings",
      "top_events": [
        "string"
      ],
      "top_hosts": [
        "string"
      ],
      "top_bots": [
        "string"
      ]
    }
  ],
  "coverage": {
    "date_from": "2019-08-24",
    "date_to": "2019-08-24",
    "days_in_range": 0,
    "checked_date_from": "2019-08-24",
    "checked_date_to": "2019-08-24",
    "days_checked": 0,
    "filters_test_accounts": true,
    "events_checked": 0,
    "sample": {
      "rate": 0.1,
      "events": 0,
      "distinct_ids": 0
    }
  }
}

Create insights generate metadata

Generate an AI-suggested name and description for an insight based on its query configuration.

Required API key scopes

insight:write

Query parameters

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

Request parameters

  • name
    string | null
  • derived_name
    string | null
  • query
  • order
    integer | null
  • deleted
    boolean
  • dashboards
    array
  • description
    string | null
  • tags
    array
  • favorited
    boolean
  • _create_in_folder
    string

Example request

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

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

Query parameters

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

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

Example response

Status 200 No response body

Create insights viewed

Record that the current user has just viewed one or more insights. Submitted ids that do not belong to the current project or that point at deleted insights are silently dropped, as are views from impersonated staff-support sessions. Returns 201 on success regardless of how many ids were retained.

Required API key scopes

insight:read

Query parameters

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

Request parameters

  • insight_ids
    array

Example request

POST /api/projects/:project_id/insights/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/viewed/\
	-d insight_ids="array"

Example response

Status 201 Views recorded.
← Previous page