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

integer

required

The ID of the project to create the insight in

Request Body

string

Name of the insight. If not provided, PostHog will generate a derived name from the query.

string

Optional description explaining what this insight shows

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

object

Legacy filter format (deprecated). Use query instead for new insights.

array

Array of dashboard IDs to add this insight to

boolean

default:true

Whether to save this insight. Set to false for temporary/unsaved insights.

boolean

default:false

Whether to mark this insight as favorited

array

Array of tag names to apply to this insight

Response Fields

integer

Unique identifier for the insight

string

Short, human-readable ID for the insight (used in URLs)

string

Name of the insight

string

Auto-generated name if no explicit name was provided

object

The query definition for this insight

any

Query results (if calculated)

object

User who created the insight

string

ISO 8601 timestamp of creation

string

ISO 8601 timestamp of when results were last calculated

boolean

Whether the results are from cache

Examples

Create Trends Insight

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
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

insight = posthog.post('/api/projects/12345/insights/', data={
    '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
})

print(f"Created insight: {insight['name']} (ID: {insight['short_id']})")

const response = await fetch('https://app.posthog.com/api/projects/12345/insights/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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
  })
});

const insight = await response.json();
console.log(`Created insight: ${insight.name} (ID: ${insight.short_id})`);

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"
      }
    }
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

insight = posthog.post('/api/projects/12345/insights/', data={
    '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'
        }
    }
})

print(f"Created funnel: {insight['short_id']}")

const response = await fetch('https://app.posthog.com/api/projects/12345/insights/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
      }
    }
  })
});

const insight = await response.json();
console.log(`Created funnel: ${insight.short_id}`);

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"
      }
    }
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

insight = posthog.post('/api/projects/12345/insights/', data={
    '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'
        }
    }
})

print(f"Created SQL insight: {insight['short_id']}")

const response = await fetch('https://app.posthog.com/api/projects/12345/insights/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
      }
    }
  })
});

const insight = await response.json();
console.log(`Created SQL insight: ${insight.short_id}`);

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]
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

insight = posthog.post('/api/projects/12345/insights/', data={
    'name': 'User Signups',
    'query': {
        'kind': 'InsightVizNode',
        'source': {
            'kind': 'TrendsQuery',
            'series': [
                {
                    'kind': 'EventsNode',
                    'event': 'signup_completed'
                }
            ],
            'dateRange': {
                'date_from': '-30d'
            }
        }
    },
    'dashboards': [456, 789]
})

print(f"Added insight to {len(insight['dashboards'])} dashboards")

const response = await fetch('https://app.posthog.com/api/projects/12345/insights/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'User Signups',
    query: {
      kind: 'InsightVizNode',
      source: {
        kind: 'TrendsQuery',
        series: [
          {
            kind: 'EventsNode',
            event: 'signup_completed'
          }
        ],
        dateRange: {
          date_from: '-30d'
        }
      }
    },
    dashboards: [456, 789]
  })
});

const insight = await response.json();
console.log(`Added insight to ${insight.dashboards.length} dashboards`);

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": "user@example.com",
    "first_name": "Jane",
    "email": "jane@example.com"
  },
  "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

error

Invalid query structure or missing required fields

{
  "detail": "Query must be a valid JSON object"
}

error

Invalid or missing API key

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

Overview

Events

Feature Flags

Cohorts

Insights

Create Insight

Create Insight

Endpoint

Path Parameters

Request Body

Response Fields

Examples

Create Trends Insight

Create Funnel Insight

Create SQL Insight

Add to Dashboard

Response

Error Responses

Notes

​Create Insight

​Endpoint

​Path Parameters

​Request Body

​Response Fields

​Examples

​Create Trends Insight

​Create Funnel Insight

​Create SQL Insight

​Add to Dashboard

​Response

​Error Responses

​Notes

Create Insight

Endpoint

Path Parameters

Request Body

Response Fields

Examples

Create Trends Insight

Create Funnel Insight

Create SQL Insight

Add to Dashboard

Response

Error Responses

Notes