Skip to main content

​
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

​
project_id
integer
required
The ID of the project to retrieve insights from

​
Query Parameters

​
saved
boolean
Filter by saved status:
  • true - Only saved insights (or insights on dashboards)
  • false - Only unsaved/temporary insights
​
insight
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
​
search
string
Search insights by name, description, or tags (case-insensitive)
​
dashboards
string
JSON array of dashboard IDs to filter by. Returns insights on ANY of the specified dashboards.Example: [123, 456]
​
tags
string
JSON array of tag names to filter byExample: ["marketing", "product"]
​
user
boolean
If true, filter to insights created by the current user
​
favorited
boolean
If true, filter to favorited insights only
​
created_by
string
JSON array of user IDs to filter by creatorExample: [123, 456]
​
date_from
string
Filter insights modified after this date (relative date format like -7d or ISO 8601)
​
date_to
string
Filter insights modified before this date
​
order
string
Sort order:
  • order (default) - Manual ordering
  • -last_viewed_at - Most recently viewed first
  • last_viewed_at - Least recently viewed first
​
limit
integer
default:100
Maximum number of results to return
​
offset
integer
default:0
Number of results to skip (for pagination)
​
basic
boolean
default:false
If true, return basic metadata only (no query results, faster response)
​
refresh
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

​
results
array
Array of insight objects
​
id
integer
Unique identifier for the insight
​
short_id
string
Short, human-readable ID (used in URLs)
​
name
string
Name of the insight
​
derived_name
string
Auto-generated name if no explicit name provided
​
description
string
Description of the insight
​
query
object
Query definition for this insight
​
result
any
Query results (if not using basic=true)
​
created_by
object
User who created the insight
​
created_at
string
ISO 8601 timestamp of creation
​
last_modified_at
string
ISO 8601 timestamp of last modification
​
last_refresh
string
ISO 8601 timestamp of when results were calculated
​
saved
boolean
Whether this insight is saved
​
favorited
boolean
Whether this insight is favorited
​
dashboards
array
Array of dashboard IDs this insight is on
​
tags
array
Array of tags applied to this insight
​
count
integer
Total number of insights matching filters
​
next
string
URL for next page of results
​
previous
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"

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

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

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

​
Recently Viewed Insights

Get insights sorted by most recently viewed: 
curl -X GET "https://app.posthog.com/api/projects/12345/insights/?order=-last_viewed_at&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
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": "[email protected]",
        "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

​
401 Unauthorized
error
Invalid or missing API key
​
403 Forbidden
error
Insufficient permissions to view insights
​
404 Not Found
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

Build docs developers (and LLMs) love

Get started for freeTalk to us