Insights API Reference

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

Example response

Status 200 No response body

Also available via the PostHog MCP server:
insights-trending-retrieve — Get most-viewed insights

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"
include_dashboards
boolean
limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/insights/trending
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/trending/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_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",
      "search_match_type": "exact",
      "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 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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/insights/viewed/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"insight_ids": "array"
	}
).json()

Example response

Status 201 Views recorded.

← Previous page

`GET`
`GET`
`POST`

Insights

Endpoints

Retrieve insights my last viewed

Query parameters

Example request

Example response

Status 200 No response body

Retrieve insights trending

Required API key scopes

Query parameters

Response

Example request

Example response

Status 200

Create insights viewed

Required API key scopes

Query parameters

Request parameters

Example request

Example response

Status 201 Views recorded.