List Insights

Retrieve a list of all insights (saved charts and analyses) in your PostHog project. Supports filtering by type, dashboard, tags, and more.

Endpoint

GET /api/projects/:project_id/insights/

Path Parameters

integer

required

The ID of the project to retrieve insights from

Query Parameters

boolean

Filter by saved status:

true - Only saved insights (or insights on dashboards)
false - Only unsaved/temporary insights

string

Filter by insight type:

TRENDS - Trends analysis
FUNNELS - Conversion funnels
RETENTION - Retention analysis
PATHS - User path analysis
STICKINESS - Stickiness/engagement
LIFECYCLE - Lifecycle analysis
SQL - SQL/HogQL queries
JSON - Custom JSON insights

string

Search insights by name, description, or tags (case-insensitive)

string

JSON array of dashboard IDs to filter by. Returns insights on ANY of the specified dashboards.Example: [123, 456]

string

JSON array of tag names to filter byExample: ["marketing", "product"]

boolean

If true, filter to insights created by the current user

boolean

If true, filter to favorited insights only

string

JSON array of user IDs to filter by creatorExample: [123, 456]

string

Filter insights modified after this date (relative date format like -7d or ISO 8601)

string

Filter insights modified before this date

string

Sort order:

order (default) - Manual ordering
-last_viewed_at - Most recently viewed first
last_viewed_at - Least recently viewed first

integer

default:100

Maximum number of results to return

integer

default:0

Number of results to skip (for pagination)

boolean

default:false

If true, return basic metadata only (no query results, faster response)

string

How to handle result calculation:

force_cache - Return cached data only
blocking - Calculate synchronously if needed
async - Kick off background calculation if needed
lazy_async - Background calculation for stale cache
force_blocking - Always calculate synchronously
force_async - Always kick off background calculation

Response Fields

array

Array of insight objects

integer

Unique identifier for the insight

string

Short, human-readable ID (used in URLs)

string

Name of the insight

string

Auto-generated name if no explicit name provided

string

Description of the insight

object

Query definition for this insight

any

Query results (if not using basic=true)

object

User who created the insight

string

ISO 8601 timestamp of creation

string

ISO 8601 timestamp of last modification

string

ISO 8601 timestamp of when results were calculated

boolean

Whether this insight is saved

boolean

Whether this insight is favorited

array

Array of dashboard IDs this insight is on

array

Array of tags applied to this insight

integer

Total number of insights matching filters

string

URL for next page of results

string

URL for previous page of results

Examples

List All Insights

Retrieve all saved insights with basic metadata:

curl -X GET "https://app.posthog.com/api/projects/12345/insights/?basic=true&saved=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

insights = posthog.get('/api/projects/12345/insights/', params={
    'basic': True,
    'saved': True
})

print(f"Found {insights['count']} insights")
for insight in insights['results']:
    print(f"- {insight['name']} (ID: {insight['short_id']})")

const response = await fetch(
  'https://app.posthog.com/api/projects/12345/insights/?basic=true&saved=true',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Found ${data.count} insights`);
data.results.forEach(insight => {
  console.log(`- ${insight.name} (ID: ${insight.short_id})`);
});

Filter by Type

Retrieve only funnel insights:

curl -X GET "https://app.posthog.com/api/projects/12345/insights/?insight=FUNNELS" \
  -H "Authorization: Bearer YOUR_API_KEY"

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

funnels = posthog.get('/api/projects/12345/insights/', params={
    'insight': 'FUNNELS'
})

print(f"Found {len(funnels['results'])} funnel insights")

const response = await fetch(
  'https://app.posthog.com/api/projects/12345/insights/?insight=FUNNELS',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Found ${data.results.length} funnel insights`);

Search Insights

Search for insights by name or description:

curl -X GET "https://app.posthog.com/api/projects/12345/insights/?search=conversion" \
  -H "Authorization: Bearer YOUR_API_KEY"

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

insights = posthog.get('/api/projects/12345/insights/', params={
    'search': 'conversion'
})

for insight in insights['results']:
    print(f"{insight['name']}: {insight['description']}")

const response = await fetch(
  'https://app.posthog.com/api/projects/12345/insights/?search=conversion',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
data.results.forEach(insight => {
  console.log(`${insight.name}: ${insight.description}`);
});

Filter by Dashboard

Get insights on specific dashboards:

curl -X GET "https://app.posthog.com/api/projects/12345/insights/?dashboards=%5B456%2C789%5D" \
  -H "Authorization: Bearer YOUR_API_KEY"

import posthog
import json

posthog.project_api_key = 'YOUR_API_KEY'

insights = posthog.get('/api/projects/12345/insights/', params={
    'dashboards': json.dumps([456, 789])
})

print(f"Found {insights['count']} insights on these dashboards")

const dashboardIds = [456, 789];
const response = await fetch(
  `https://app.posthog.com/api/projects/12345/insights/?dashboards=${encodeURIComponent(JSON.stringify(dashboardIds))}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Found ${data.count} insights on these dashboards`);

Response

{
  "count": 145,
  "next": "https://app.posthog.com/api/projects/12345/insights/?limit=100&offset=100",
  "previous": null,
  "results": [
    {
      "id": 9876,
      "short_id": "abc123",
      "name": "User Signups",
      "derived_name": "signup_completed count",
      "description": "Daily user signups over time",
      "query": {
        "kind": "InsightVizNode",
        "source": {
          "kind": "TrendsQuery",
          "series": [
            {
              "kind": "EventsNode",
              "event": "signup_completed"
            }
          ]
        }
      },
      "result": null,
      "created_by": {
        "id": 123,
        "email": "jane@example.com",
        "first_name": "Jane"
      },
      "created_at": "2024-01-10T09:00:00Z",
      "last_modified_at": "2024-01-12T14:30:00Z",
      "last_refresh": "2024-01-15T10:00:00Z",
      "saved": true,
      "favorited": false,
      "dashboards": [456],
      "tags": ["growth", "metrics"]
    }
  ]
}

Error Responses

error

Invalid or missing API key

error

Insufficient permissions to view insights

error

Project not found

Notes

Use basic=true for faster responses when you only need metadata
Results are paginated with a default limit of 100
Deleted insights are excluded from results
The refresh parameter controls whether and how to recalculate results
Use force_cache for fastest responses (may return stale data)
Multiple filters are combined with AND logic
Search is case-insensitive and matches partial strings

Overview

Events

Feature Flags

Cohorts

Insights

List Insights

List Insights

Endpoint

Path Parameters

Query Parameters

Response Fields

Examples

List All Insights

Filter by Type

Search Insights

Filter by Dashboard

Recently Viewed Insights

Response

Error Responses

Notes

​List Insights

​Endpoint

​Path Parameters

​Query Parameters

​Response Fields

​Examples

​List All Insights

​Filter by Type

​Search Insights

​Filter by Dashboard

​Recently Viewed Insights

​Response

​Error Responses

​Notes

List Insights

Endpoint

Path Parameters

Query Parameters

Response Fields

Examples

List All Insights

Filter by Type

Search Insights

Filter by Dashboard

Recently Viewed Insights

Response

Error Responses

Notes