Insights-2 API Reference

Retrieve environments 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/environments/:environment_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/environments/:environment_id/insights/my_last_viewed/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/insights/my_last_viewed/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Returns insights ranked by view count over the last N days (default 7), highest first. Each result includes the same metadata as the standard insights list, plus a view_count and up to 3 recent viewers. Useful for surfacing the most-used insights in a project.

Required API key scopes

insight:read

Query parameters

days
integer
format
string
One of: "csv""json"
limit
integer
offset
integer

Response

Example request

GET /api/environments/:environment_id/insights/trending
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:environment_id/insights/trending/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{environment_id}/insights/trending/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example 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",
      "query": null,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "description": "string",
      "last_refresh": "2019-08-24T14:15:22Z",
      "refreshing": true,
      "tags": [
        null
      ],
      "updated_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": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "last_modified_at": "2019-08-24T14:15:22Z",
      "favorited": true,
      "user_access_level": "string",
      "last_viewed_at": "2019-08-24T14:15:22Z",
      "view_count": 0,
      "viewers": [
        {
          "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": {},
          "role_at_organization": "engineering"
        }
      ],
      "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": {},
        "role_at_organization": "engineering"
      }
    }
  ]
}

Create environments insights viewed

Update insight view timestamps. Expects: {"insight_ids": [1, 2, 3, ...]}

Required API key scopes

insight:read

Query parameters

format
string
One of: "csv""json"

Request parameters

name
stringnull
derived_name
stringnull
query
order
integernull
deleted
boolean
dashboards
array
description
stringnull
tags
array
favorited
boolean
_create_in_folder
string

Example request

POST /api/environments/:environment_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/environments/:environment_id/insights/viewed/\
	-d name=["string","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{environment_id}/insights/viewed/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200 No response body

List all insights

DRF ViewSet mixin that gates coalesced responses behind permission checks.

The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Required API key scopes

insight:read

Query parameters

basic
boolean
created_by
string
created_date_from
string
created_date_to
string
dashboards
string
date_from
string
date_to
string
favorited
boolean
format
string
One of: "csv""json"
insight
string
One of: "FUNNELS""JSON""LIFECYCLE""PATHS""RETENTION""SQL""STICKINESS""TRENDS"
last_viewed_date_from
string
last_viewed_date_to
string
limit
integer
offset
integer
refresh
string
Default: force_cache
One of: "async""async_except_on_cache_miss""blocking""force_async""force_blocking""force_cache""lazy_async"
saved
boolean
search
string
short_id
string
tags
string
user
boolean

Response

Example 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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example 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",
      "query": {
        "embedded": null,
        "full": null,
        "hidePersonsModal": null,
        "hideTooltipOnScroll": null,
        "kind": "InsightVizNode",
        "showCorrelationTable": null,
        "showFilters": null,
        "showHeader": null,
        "showLastComputation": null,
        "showLastComputationRefresh": null,
        "showResults": null,
        "showTable": null,
        "source": {
          "aggregation_group_type_index": null,
          "breakdownFilter": null,
          "compareFilter": null,
          "conversionGoal": null,
          "dataColorTheme": null,
          "dateRange": null,
          "filterTestAccounts": false,
          "interval": "day",
          "kind": "TrendsQuery",
          "modifiers": null,
          "properties": [],
          "response": null,
          "samplingFactor": null,
          "series": [
            {
              "custom_name": null,
              "fixedProperties": null,
              "kind": "GroupNode",
              "limit": null,
              "math": null,
              "math_group_type_index": null,
              "math_hogql": null,
              "math_multiplier": null,
              "math_property": null,
              "math_property_revenue_currency": null,
              "math_property_type": null,
              "name": null,
              "nodes": [
                {
                  "custom_name": null,
                  "event": null,
                  "fixedProperties": null,
                  "kind": "EventsNode",
                  "limit": null,
                  "math": null,
                  "math_group_type_index": null,
                  "math_hogql": null,
                  "math_multiplier": null,
                  "math_property": null,
                  "math_property_revenue_currency": null,
                  "math_property_type": null,
                  "name": null,
                  "optionalInFunnel": null,
                  "orderBy": null,
                  "properties": null,
                  "response": null,
                  "version": null
                }
              ],
              "operator": "AND",
              "optionalInFunnel": null,
              "orderBy": null,
              "properties": null,
              "response": null,
              "version": null
            }
          ],
          "tags": null,
          "trendsFilter": null,
          "version": null
        },
        "suppressSessionAnalysisWarning": null,
        "version": null,
        "vizSpecificOptions": null
      },
      "order": -2147483648,
      "deleted": true,
      "dashboards": [
        0
      ],
      "dashboard_tiles": [
        {
          "id": 0,
          "dashboard_id": 0,
          "deleted": true
        }
      ],
      "last_refresh": "2019-08-24T14:15:22Z",
      "cache_target_age": "2019-08-24T14:15:22Z",
      "next_allowed_client_refresh": "2019-08-24T14:15:22Z",
      "result": null,
      "hasMore": true,
      "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": {},
        "role_at_organization": "engineering"
      },
      "description": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "tags": [
        null
      ],
      "favorited": 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": {},
        "role_at_organization": "engineering"
      },
      "is_sample": true,
      "effective_restriction_level": 21,
      "effective_privilege_level": 21,
      "user_access_level": "string",
      "timezone": "string",
      "is_cached": true,
      "query_status": null,
      "hogql": "string",
      "types": [
        null
      ],
      "resolved_date_range": {
        "date_from": "2019-08-24T14:15:22Z",
        "date_to": "2019-08-24T14:15:22Z"
      },
      "_create_in_folder": "string",
      "alerts": [
        null
      ],
      "last_viewed_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create insights

DRF ViewSet mixin that gates coalesced responses behind permission checks.

The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Required API key scopes

insight:write

Query parameters

format
string
One of: "csv""json"

Request parameters

name
stringnull
derived_name
stringnull
query
order
integernull
deleted
boolean
dashboards
array
description
stringnull
tags
array
favorited
boolean
_create_in_folder
string

Response

Example 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","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/insights/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": 0,
  "short_id": "string",
  "name": "string",
  "derived_name": "string",
  "query": {
    "embedded": null,
    "full": null,
    "hidePersonsModal": null,
    "hideTooltipOnScroll": null,
    "kind": "InsightVizNode",
    "showCorrelationTable": null,
    "showFilters": null,
    "showHeader": null,
    "showLastComputation": null,
    "showLastComputationRefresh": null,
    "showResults": null,
    "showTable": null,
    "source": {
      "aggregation_group_type_index": null,
      "breakdownFilter": null,
      "compareFilter": null,
      "conversionGoal": null,
      "dataColorTheme": null,
      "dateRange": null,
      "filterTestAccounts": false,
      "interval": "day",
      "kind": "TrendsQuery",
      "modifiers": null,
      "properties": [],
      "response": null,
      "samplingFactor": null,
      "series": [
        {
          "custom_name": null,
          "fixedProperties": null,
          "kind": "GroupNode",
          "limit": null,
          "math": null,
          "math_group_type_index": null,
          "math_hogql": null,
          "math_multiplier": null,
          "math_property": null,
          "math_property_revenue_currency": null,
          "math_property_type": null,
          "name": null,
          "nodes": [
            {
              "custom_name": null,
              "event": null,
              "fixedProperties": null,
              "kind": "EventsNode",
              "limit": null,
              "math": null,
              "math_group_type_index": null,
              "math_hogql": null,
              "math_multiplier": null,
              "math_property": null,
              "math_property_revenue_currency": null,
              "math_property_type": null,
              "name": null,
              "optionalInFunnel": null,
              "orderBy": null,
              "properties": null,
              "response": null,
              "version": null
            }
          ],
          "operator": "AND",
          "optionalInFunnel": null,
          "orderBy": null,
          "properties": null,
          "response": null,
          "version": null
        }
      ],
      "tags": null,
      "trendsFilter": null,
      "version": null
    },
    "suppressSessionAnalysisWarning": null,
    "version": null,
    "vizSpecificOptions": null
  },
  "order": -2147483648,
  "deleted": true,
  "dashboards": [
    0
  ],
  "dashboard_tiles": [
    {
      "id": 0,
      "dashboard_id": 0,
      "deleted": true
    }
  ],
  "last_refresh": "2019-08-24T14:15:22Z",
  "cache_target_age": "2019-08-24T14:15:22Z",
  "next_allowed_client_refresh": "2019-08-24T14:15:22Z",
  "result": null,
  "hasMore": true,
  "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": {},
    "role_at_organization": "engineering"
  },
  "description": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "tags": [
    null
  ],
  "favorited": 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": {},
    "role_at_organization": "engineering"
  },
  "is_sample": true,
  "effective_restriction_level": 21,
  "effective_privilege_level": 21,
  "user_access_level": "string",
  "timezone": "string",
  "is_cached": true,
  "query_status": null,
  "hogql": "string",
  "types": [
    null
  ],
  "resolved_date_range": {
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z"
  },
  "_create_in_folder": "string",
  "alerts": [
    null
  ],
  "last_viewed_at": "2019-08-24T14:15:22Z"
}

List all insights thresholds

Required API key scopes

alert:read

Path parameters

insight_id
integer

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/insights/:insight_id/thresholds
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/thresholds/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/{insight_id}/thresholds/".format(
        project_id=project_id,
		insight_id="<the insight id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example 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": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "created_at": "2019-08-24T14:15:22Z",
      "name": "string",
      "configuration": {
        "bounds": null,
        "type": "absolute"
      },
      "alerts": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "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": {},
            "role_at_organization": "engineering"
          },
          "created_at": "2019-08-24T14:15:22Z",
          "insight": 0,
          "name": "string",
          "subscribed_users": [
            0
          ],
          "threshold": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "created_at": "2019-08-24T14:15:22Z",
            "name": "string",
            "configuration": {
              "bounds": null,
              "type": "absolute"
            }
          },
          "condition": {
            "type": "absolute_value"
          },
          "state": "string",
          "enabled": true,
          "last_notified_at": "2019-08-24T14:15:22Z",
          "last_checked_at": "2019-08-24T14:15:22Z",
          "next_check_at": "2019-08-24T14:15:22Z",
          "checks": [
            {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "created_at": "2019-08-24T14:15:22Z",
              "calculated_value": 0,
              "state": "Firing",
              "targets_notified": true,
              "anomaly_scores": null,
              "triggered_points": null,
              "triggered_dates": null,
              "interval": "string",
              "triggered_metadata": null,
              "investigation_status": "pending",
              "investigation_verdict": "true_positive",
              "investigation_summary": "string",
              "investigation_notebook_short_id": "string",
              "notification_sent_at": "2019-08-24T14:15:22Z",
              "notification_suppressed_by_agent": true
            }
          ],
          "checks_total": 0,
          "config": {
            "check_ongoing_interval": null,
            "series_index": 0,
            "type": "TrendsAlertConfig"
          },
          "detector_config": {
            "detectors": [
              {
                "preprocessing": null,
                "threshold": null,
                "type": "zscore",
                "window": null
              }
            ],
            "operator": "and",
            "type": "ensemble"
          },
          "calculation_interval": "hourly",
          "snoozed_until": "string",
          "skip_weekend": true,
          "schedule_restriction": {
            "blocked_windows": [
              {
                "start": "string",
                "end": "string"
              }
            ]
          },
          "last_value": 0,
          "investigation_agent_enabled": true,
          "investigation_gates_notifications": true,
          "investigation_inconclusive_action": "notify"
        }
      ]
    }
  ]
}

Retrieve insights thresholds

Required API key scopes

alert:read

Path parameters

id
string
insight_id
integer

Response

Example request

GET /api/projects/:project_id/insights/:insight_id/thresholds/: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/:insight_id/thresholds/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/{insight_id}/thresholds/{insights-2_id}/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>",
		insight_id="<the insight id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_at": "2019-08-24T14:15:22Z",
  "name": "string",
  "configuration": {
    "bounds": null,
    "type": "absolute"
  },
  "alerts": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "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": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "insight": 0,
      "name": "string",
      "subscribed_users": [
        0
      ],
      "threshold": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "created_at": "2019-08-24T14:15:22Z",
        "name": "string",
        "configuration": {
          "bounds": null,
          "type": "absolute"
        }
      },
      "condition": {
        "type": "absolute_value"
      },
      "state": "string",
      "enabled": true,
      "last_notified_at": "2019-08-24T14:15:22Z",
      "last_checked_at": "2019-08-24T14:15:22Z",
      "next_check_at": "2019-08-24T14:15:22Z",
      "checks": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "created_at": "2019-08-24T14:15:22Z",
          "calculated_value": 0,
          "state": "Firing",
          "targets_notified": true,
          "anomaly_scores": null,
          "triggered_points": null,
          "triggered_dates": null,
          "interval": "string",
          "triggered_metadata": null,
          "investigation_status": "pending",
          "investigation_verdict": "true_positive",
          "investigation_summary": "string",
          "investigation_notebook_short_id": "string",
          "notification_sent_at": "2019-08-24T14:15:22Z",
          "notification_suppressed_by_agent": true
        }
      ],
      "checks_total": 0,
      "config": {
        "check_ongoing_interval": null,
        "series_index": 0,
        "type": "TrendsAlertConfig"
      },
      "detector_config": {
        "detectors": [
          {
            "preprocessing": null,
            "threshold": null,
            "type": "zscore",
            "window": null
          }
        ],
        "operator": "and",
        "type": "ensemble"
      },
      "calculation_interval": "hourly",
      "snoozed_until": "string",
      "skip_weekend": true,
      "schedule_restriction": {
        "blocked_windows": [
          {
            "start": "string",
            "end": "string"
          }
        ]
      },
      "last_value": 0,
      "investigation_agent_enabled": true,
      "investigation_gates_notifications": true,
      "investigation_inconclusive_action": "notify"
    }
  ]
}

Retrieve insights

DRF ViewSet mixin that gates coalesced responses behind permission checks.

The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Required API key scopes

insight:read

Path parameters

id

Query parameters

filters_override
string
format
string
One of: "csv""json"
from_dashboard
integer
refresh
string
Default: force_cache
One of: "async""async_except_on_cache_miss""blocking""force_async""force_blocking""force_cache""lazy_async"
variables_override
string

Response

Example 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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/{insights-2_id}/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "short_id": "string",
  "name": "string",
  "derived_name": "string",
  "query": {
    "embedded": null,
    "full": null,
    "hidePersonsModal": null,
    "hideTooltipOnScroll": null,
    "kind": "InsightVizNode",
    "showCorrelationTable": null,
    "showFilters": null,
    "showHeader": null,
    "showLastComputation": null,
    "showLastComputationRefresh": null,
    "showResults": null,
    "showTable": null,
    "source": {
      "aggregation_group_type_index": null,
      "breakdownFilter": null,
      "compareFilter": null,
      "conversionGoal": null,
      "dataColorTheme": null,
      "dateRange": null,
      "filterTestAccounts": false,
      "interval": "day",
      "kind": "TrendsQuery",
      "modifiers": null,
      "properties": [],
      "response": null,
      "samplingFactor": null,
      "series": [
        {
          "custom_name": null,
          "fixedProperties": null,
          "kind": "GroupNode",
          "limit": null,
          "math": null,
          "math_group_type_index": null,
          "math_hogql": null,
          "math_multiplier": null,
          "math_property": null,
          "math_property_revenue_currency": null,
          "math_property_type": null,
          "name": null,
          "nodes": [
            {
              "custom_name": null,
              "event": null,
              "fixedProperties": null,
              "kind": "EventsNode",
              "limit": null,
              "math": null,
              "math_group_type_index": null,
              "math_hogql": null,
              "math_multiplier": null,
              "math_property": null,
              "math_property_revenue_currency": null,
              "math_property_type": null,
              "name": null,
              "optionalInFunnel": null,
              "orderBy": null,
              "properties": null,
              "response": null,
              "version": null
            }
          ],
          "operator": "AND",
          "optionalInFunnel": null,
          "orderBy": null,
          "properties": null,
          "response": null,
          "version": null
        }
      ],
      "tags": null,
      "trendsFilter": null,
      "version": null
    },
    "suppressSessionAnalysisWarning": null,
    "version": null,
    "vizSpecificOptions": null
  },
  "order": -2147483648,
  "deleted": true,
  "dashboards": [
    0
  ],
  "dashboard_tiles": [
    {
      "id": 0,
      "dashboard_id": 0,
      "deleted": true
    }
  ],
  "last_refresh": "2019-08-24T14:15:22Z",
  "cache_target_age": "2019-08-24T14:15:22Z",
  "next_allowed_client_refresh": "2019-08-24T14:15:22Z",
  "result": null,
  "hasMore": true,
  "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": {},
    "role_at_organization": "engineering"
  },
  "description": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "tags": [
    null
  ],
  "favorited": 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": {},
    "role_at_organization": "engineering"
  },
  "is_sample": true,
  "effective_restriction_level": 21,
  "effective_privilege_level": 21,
  "user_access_level": "string",
  "timezone": "string",
  "is_cached": true,
  "query_status": null,
  "hogql": "string",
  "types": [
    null
  ],
  "resolved_date_range": {
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z"
  },
  "_create_in_folder": "string",
  "alerts": [
    null
  ],
  "last_viewed_at": "2019-08-24T14:15:22Z"
}

Update insights

DRF ViewSet mixin that gates coalesced responses behind permission checks.

The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Required API key scopes

insight:write

Path parameters

id

Query parameters

format
string
One of: "csv""json"

Request parameters

name
stringnull
derived_name
stringnull
query
order
integernull
deleted
boolean
dashboards
array
description
stringnull
tags
array
favorited
boolean
_create_in_folder
string

Response

Example 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","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/insights/{insights-2_id}/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": 0,
  "short_id": "string",
  "name": "string",
  "derived_name": "string",
  "query": {
    "embedded": null,
    "full": null,
    "hidePersonsModal": null,
    "hideTooltipOnScroll": null,
    "kind": "InsightVizNode",
    "showCorrelationTable": null,
    "showFilters": null,
    "showHeader": null,
    "showLastComputation": null,
    "showLastComputationRefresh": null,
    "showResults": null,
    "showTable": null,
    "source": {
      "aggregation_group_type_index": null,
      "breakdownFilter": null,
      "compareFilter": null,
      "conversionGoal": null,
      "dataColorTheme": null,
      "dateRange": null,
      "filterTestAccounts": false,
      "interval": "day",
      "kind": "TrendsQuery",
      "modifiers": null,
      "properties": [],
      "response": null,
      "samplingFactor": null,
      "series": [
        {
          "custom_name": null,
          "fixedProperties": null,
          "kind": "GroupNode",
          "limit": null,
          "math": null,
          "math_group_type_index": null,
          "math_hogql": null,
          "math_multiplier": null,
          "math_property": null,
          "math_property_revenue_currency": null,
          "math_property_type": null,
          "name": null,
          "nodes": [
            {
              "custom_name": null,
              "event": null,
              "fixedProperties": null,
              "kind": "EventsNode",
              "limit": null,
              "math": null,
              "math_group_type_index": null,
              "math_hogql": null,
              "math_multiplier": null,
              "math_property": null,
              "math_property_revenue_currency": null,
              "math_property_type": null,
              "name": null,
              "optionalInFunnel": null,
              "orderBy": null,
              "properties": null,
              "response": null,
              "version": null
            }
          ],
          "operator": "AND",
          "optionalInFunnel": null,
          "orderBy": null,
          "properties": null,
          "response": null,
          "version": null
        }
      ],
      "tags": null,
      "trendsFilter": null,
      "version": null
    },
    "suppressSessionAnalysisWarning": null,
    "version": null,
    "vizSpecificOptions": null
  },
  "order": -2147483648,
  "deleted": true,
  "dashboards": [
    0
  ],
  "dashboard_tiles": [
    {
      "id": 0,
      "dashboard_id": 0,
      "deleted": true
    }
  ],
  "last_refresh": "2019-08-24T14:15:22Z",
  "cache_target_age": "2019-08-24T14:15:22Z",
  "next_allowed_client_refresh": "2019-08-24T14:15:22Z",
  "result": null,
  "hasMore": true,
  "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": {},
    "role_at_organization": "engineering"
  },
  "description": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "tags": [
    null
  ],
  "favorited": 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": {},
    "role_at_organization": "engineering"
  },
  "is_sample": true,
  "effective_restriction_level": 21,
  "effective_privilege_level": 21,
  "user_access_level": "string",
  "timezone": "string",
  "is_cached": true,
  "query_status": null,
  "hogql": "string",
  "types": [
    null
  ],
  "resolved_date_range": {
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z"
  },
  "_create_in_folder": "string",
  "alerts": [
    null
  ],
  "last_viewed_at": "2019-08-24T14:15:22Z"
}

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

Query parameters

format
string
One of: "csv""json"

Example 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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/insights/{insights-2_id}/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 405 No response body

Retrieve insights activity

Audit trail for a single insight — every change made to it, by whom, and when. Use this when you want the change history of a specific insight; use the project-wide activity endpoint for a broader view.

Required API key scopes

activity_log:read

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"
limit
integer
page
integer

Response

Example 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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/{insights-2_id}/activity/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "user": {},
      "activity": "string",
      "scope": "string",
      "item_id": "string",
      "detail": {
        "id": "string",
        "changes": [
          {
            "type": "string",
            "action": "string",
            "field": "string",
            "before": null,
            "after": null
          }
        ],
        "merge": {
          "type": "string",
          "source": null,
          "target": null
        },
        "trigger": {
          "job_type": "string",
          "job_id": "string",
          "payload": null
        },
        "name": "string",
        "short_id": "string",
        "type": "string"
      },
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next": "http://example.com",
  "previous": "http://example.com",
  "total_count": 0
}

Retrieve insights analyze

DRF ViewSet mixin that gates coalesced responses behind permission checks.

The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/projects/:project_id/insights/:id/analyze
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/analyze/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/{insights-2_id}/analyze/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve insights suggestions

DRF ViewSet mixin that gates coalesced responses behind permission checks.

The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Example request

GET /api/projects/:project_id/insights/:id/suggestions
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/suggestions/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/{insights-2_id}/suggestions/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Create insights suggestions

DRF ViewSet mixin that gates coalesced responses behind permission checks.

The QueryCoalescingMiddleware attaches cached response data to request.META["_coalesced_response"] for followers. This mixin runs DRF's initial() (auth + permissions + throttling) before returning the cached response, ensuring the request is authorized.

Path parameters

id
integer

Query parameters

format
string
One of: "csv""json"

Request parameters

name
stringnull
derived_name
stringnull
query
order
integernull
deleted
boolean
dashboards
array
description
stringnull
tags
array
favorited
boolean
_create_in_folder
string

Example request

POST /api/projects/:project_id/insights/:id/suggestions
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/suggestions/\
	-d name=["string","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/insights/{insights-2_id}/suggestions/".format(
        project_id=project_id,
		insights-2_id="<the insights-2 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200 No response body

Retrieve insights all activity

Project-wide audit trail across all insights — who created, edited, deleted, or restored insights, what changed (with before/after diffs), and when. Useful for surfacing what people (or agents) have been working on recently.

Required API key scopes

activity_log:read

Query parameters

format
string
One of: "csv""json"
limit
integer
page
integer

Response

Example 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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/insights/activity/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "user": {},
      "activity": "string",
      "scope": "string",
      "item_id": "string",
      "detail": {
        "id": "string",
        "changes": [
          {
            "type": "string",
            "action": "string",
            "field": "string",
            "before": null,
            "after": null
          }
        ],
        "merge": {
          "type": "string",
          "source": null,
          "target": null
        },
        "trigger": {
          "job_type": "string",
          "job_id": "string",
          "payload": null
        },
        "name": "string",
        "short_id": "string",
        "type": "string"
      },
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next": "http://example.com",
  "previous": "http://example.com",
  "total_count": 0
}

← Previous pageNext page →

`GET`
`GET`
`POST`
`GET`
`POST`
`GET`
`POST`
`DELETE`
`POST`
`GET`
`GET`
`GET`
`PATCH`
`DELETE`
`GET`
`GET`
`GET`
`POST`
`GET`

Insights-2

Endpoints

Retrieve environments insights my last viewed

Query parameters

Example request

Example response

Status 200 No response body

Retrieve environments insights trending

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create environments insights viewed

Required API key scopes

Query parameters

Request parameters

Example request

Example response

Status 200 No response body

List all insights

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create insights

Required API key scopes

Query parameters

Request parameters

Response

Example request

Example response

Status 201

List all insights sharing

Required API key scopes

Path parameters

Example request

Example response

Status 200

Create insights sharing passwords

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

Delete insights sharing passwords

Required API key scopes

Path parameters

Example request

Example response

Status 204 No response body

Create insights sharing refresh

Required API key scopes

Path parameters

Request parameters

Response

Example request

Example response

Status 200

List all insights thresholds

Required API key scopes

Path parameters

Query parameters

Response

Example request

Example response

Status 200

Retrieve insights thresholds

Required API key scopes

Path parameters

Response

Example request

Example response

Status 200

Retrieve insights