Skip to main content

​
Create Insight

Create a new insight to save a chart, analysis, or visualization in PostHog. Insights can contain trends, funnels, retention analysis, path analysis, and more.

​
Endpoint

POST /api/projects/:project_id/insights/

​
Path Parameters

​
project_id
integer
required
The ID of the project to create the insight in

​
Request Body

​
name
string
Name of the insight. If not provided, PostHog will generate a derived name from the query.
​
description
string
Optional description explaining what this insight shows
​
query
object
required
The query definition for this insight. The kind field determines the query type:
  • InsightVizNode — Product analytics (trends, funnels, retention, paths, stickiness, lifecycle)
  • DataVisualizationNode — SQL insights using HogQL
  • DataTableNode — Raw data tables
  • HogQuery — Hog language queries
Example for a trends query:
{
  "kind": "InsightVizNode",
  "source": {
    "kind": "TrendsQuery",
    "series": [
      {
        "kind": "EventsNode",
        "event": "$pageview",
        "name": "$pageview"
      }
    ],
    "dateRange": {
      "date_from": "-7d"
    }
  }
}
​
filters
object
Legacy filter format (deprecated). Use query instead for new insights.
​
dashboards
array
Array of dashboard IDs to add this insight to
​
saved
boolean
default:true
Whether to save this insight. Set to false for temporary/unsaved insights.
​
favorited
boolean
default:false
Whether to mark this insight as favorited
​
tags
array
Array of tag names to apply to this insight

​
Response Fields

​
id
integer
Unique identifier for the insight
​
short_id
string
Short, human-readable ID for the insight (used in URLs)
​
name
string
Name of the insight
​
derived_name
string
Auto-generated name if no explicit name was provided
​
query
object
The query definition for this insight
​
result
any
Query results (if calculated)
​
created_by
object
User who created the insight
​
created_at
string
ISO 8601 timestamp of creation
​
last_refresh
string
ISO 8601 timestamp of when results were last calculated
​
is_cached
boolean
Whether the results are from cache

​
Examples

Create an insight showing pageview trends over the last 7 days: 
curl -X POST https://app.posthog.com/api/projects/12345/insights/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pageviews Last 7 Days",
    "description": "Daily pageview count for the past week",
    "query": {
      "kind": "InsightVizNode",
      "source": {
        "kind": "TrendsQuery",
        "series": [
          {
            "kind": "EventsNode",
            "event": "$pageview",
            "name": "$pageview"
          }
        ],
        "dateRange": {
          "date_from": "-7d"
        },
        "interval": "day"
      }
    },
    "saved": true
  }'

​
Create Funnel Insight

Create a conversion funnel insight: 
curl -X POST https://app.posthog.com/api/projects/12345/insights/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Signup Funnel",
    "description": "Conversion from signup to first action",
    "query": {
      "kind": "InsightVizNode",
      "source": {
        "kind": "FunnelsQuery",
        "series": [
          {
            "kind": "EventsNode",
            "event": "signup_started",
            "name": "Signup Started"
          },
          {
            "kind": "EventsNode",
            "event": "signup_completed",
            "name": "Signup Completed"
          },
          {
            "kind": "EventsNode",
            "event": "first_action",
            "name": "First Action"
          }
        ],
        "dateRange": {
          "date_from": "-30d"
        },
        "funnelWindowInterval": 7,
        "funnelWindowIntervalUnit": "day"
      }
    }
  }'

​
Create SQL Insight

Create a SQL-based insight using HogQL: 
curl -X POST https://app.posthog.com/api/projects/12345/insights/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Top Events by Count",
    "query": {
      "kind": "DataVisualizationNode",
      "source": {
        "kind": "HogQLQuery",
        "query": "SELECT event, count() as count FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY event ORDER BY count DESC LIMIT 10"
      },
      "display": {
        "type": "table"
      }
    }
  }'

​
Add to Dashboard

Create an insight and add it to a dashboard: 
curl -X POST https://app.posthog.com/api/projects/12345/insights/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Signups",
    "query": {
      "kind": "InsightVizNode",
      "source": {
        "kind": "TrendsQuery",
        "series": [
          {
            "kind": "EventsNode",
            "event": "signup_completed"
          }
        ],
        "dateRange": {
          "date_from": "-30d"
        }
      }
    },
    "dashboards": [456, 789]
  }'

​
Response

{
  "id": 9876,
  "short_id": "abc123",
  "name": "Pageviews Last 7 Days",
  "derived_name": "$pageview count",
  "description": "Daily pageview count for the past week",
  "query": {
    "kind": "InsightVizNode",
    "source": {
      "kind": "TrendsQuery",
      "series": [
        {
          "kind": "EventsNode",
          "event": "$pageview",
          "name": "$pageview"
        }
      ],
      "dateRange": {
        "date_from": "-7d"
      },
      "interval": "day"
    }
  },
  "result": null,
  "created_by": {
    "id": 123,
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "distinct_id": "[email protected]",
    "first_name": "Jane",
    "email": "[email protected]"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "last_modified_at": "2024-01-15T10:30:00Z",
  "last_refresh": null,
  "is_cached": false,
  "saved": true,
  "favorited": false,
  "dashboards": [],
  "tags": []
}

​
Error Responses

​
400 Bad Request
error
Invalid query structure or missing required fields
{
  "detail": "Query must be a valid JSON object"
}
​
401 Unauthorized
error
Invalid or missing API key
​
403 Forbidden
error
Insufficient permissions to create insights

​
Notes

  • Insights are not automatically calculated on creation; results are calculated on first view or when explicitly refreshed
  • Use the query field for all new insights (the filters field is deprecated)
  • Insights can be added to multiple dashboards
  • Set saved: false to create temporary/exploratory insights that don’t clutter your saved insights
  • Query results are cached for performance; use the refresh parameter when retrieving to force recalculation

Build docs developers (and LLMs) love

Get started for freeTalk to us