Query Insights

Execute insight queries and retrieve results without creating a saved insight. This endpoint is useful for exploratory analysis, building custom dashboards, or programmatically analyzing your PostHog data.

Endpoint

POST /api/projects/:project_id/query/

Path Parameters

integer

required

The ID of the project to query

Query Parameters

string

How to handle result calculation:

force_cache - Return cached data only (fastest, may return cache miss)
blocking - Calculate synchronously if cache is stale
async - Kick off background calculation if needed, return immediately
lazy_async - Background calculation for somewhat stale cache
force_blocking - Always calculate synchronously
force_async - Always calculate in background

Default: force_cache

string

Optional client-provided query ID for tracking and cancellation

Request Body

The request body should contain a query object matching one of the supported query types.

Trends Query

string

required

Set to TrendsQuery for trends analysis

array

required

Array of event or action nodes to analyze

object

Date range for the analysis (e.g., {"date_from": "-7d"})

string

Time interval: hour, day, week, month

object

Break down results by properties

array

Filter events by properties

Funnels Query

string

required

Set to FunnelsQuery for conversion funnel analysis

array

required

Ordered array of funnel steps (events or actions)

number

Time window for conversion (e.g., 7)

string

Unit for funnel window: hour, day, week, month

HogQL Query

string

required

Set to HogQLQuery for SQL queries

string

required

HogQL (SQL-like) query string

Response Fields

any

Query results (format depends on query type)

boolean

Whether there are more results available (for paginated queries)

array

Column definitions (for table results)

array

Data types for each column

string

The HogQL query that was executed (for debugging)

object

Query execution status and metadata

string

Query ID

boolean

Whether query execution is complete

boolean

Whether an error occurred

string

Error message if query failed

string

ISO 8601 timestamp of when results were calculated

boolean

Whether results came from cache

string

Timezone used for date calculations

array

Performance timing information

Examples

Trends Query

Query pageview trends over the last 7 days:

curl -X POST https://app.posthog.com/api/projects/12345/query/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "TrendsQuery",
    "series": [
      {
        "kind": "EventsNode",
        "event": "$pageview",
        "name": "$pageview"
      }
    ],
    "dateRange": {
      "date_from": "-7d"
    },
    "interval": "day"
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

result = posthog.post('/api/projects/12345/query/', data={
    'kind': 'TrendsQuery',
    'series': [
        {
            'kind': 'EventsNode',
            'event': '$pageview',
            'name': '$pageview'
        }
    ],
    'dateRange': {
        'date_from': '-7d'
    },
    'interval': 'day'
})

print(f"Results: {result['results']}")
print(f"Cached: {result['is_cached']}")

const response = await fetch('https://app.posthog.com/api/projects/12345/query/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    kind: 'TrendsQuery',
    series: [
      {
        kind: 'EventsNode',
        event: '$pageview',
        name: '$pageview'
      }
    ],
    dateRange: {
      date_from: '-7d'
    },
    interval: 'day'
  })
});

const result = await response.json();
console.log(`Results:`, result.results);
console.log(`Cached: ${result.is_cached}`);

Funnel Query

Analyze conversion through a signup funnel:

curl -X POST "https://app.posthog.com/api/projects/12345/query/?refresh=blocking" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "FunnelsQuery",
    "series": [
      {
        "kind": "EventsNode",
        "event": "signup_started",
        "name": "Started Signup"
      },
      {
        "kind": "EventsNode",
        "event": "signup_completed",
        "name": "Completed Signup"
      }
    ],
    "dateRange": {
      "date_from": "-30d"
    },
    "funnelWindowInterval": 1,
    "funnelWindowIntervalUnit": "day"
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

result = posthog.post('/api/projects/12345/query/', 
    params={'refresh': 'blocking'},
    data={
        'kind': 'FunnelsQuery',
        'series': [
            {
                'kind': 'EventsNode',
                'event': 'signup_started',
                'name': 'Started Signup'
            },
            {
                'kind': 'EventsNode',
                'event': 'signup_completed',
                'name': 'Completed Signup'
            }
        ],
        'dateRange': {
            'date_from': '-30d'
        },
        'funnelWindowInterval': 1,
        'funnelWindowIntervalUnit': 'day'
    }
)

print(f"Conversion rate: {result['results'][0]['conversion_rate']}%")

const response = await fetch('https://app.posthog.com/api/projects/12345/query/?refresh=blocking', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    kind: 'FunnelsQuery',
    series: [
      {
        kind: 'EventsNode',
        event: 'signup_started',
        name: 'Started Signup'
      },
      {
        kind: 'EventsNode',
        event: 'signup_completed',
        name: 'Completed Signup'
      }
    ],
    dateRange: {
      date_from: '-30d'
    },
    funnelWindowInterval: 1,
    funnelWindowIntervalUnit: 'day'
  })
});

const result = await response.json();
console.log(`Conversion rate: ${result.results[0].conversion_rate}%`);

HogQL Query

Run a SQL query using HogQL:

curl -X POST https://app.posthog.com/api/projects/12345/query/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

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

for row in result['results']:
    print(f"{row[0]}: {row[1]} events")

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

const result = await response.json();
result.results.forEach(row => {
  console.log(`${row[0]}: ${row[1]} events`);
});

Query with Breakdown

Analyze events broken down by a property:

curl -X POST https://app.posthog.com/api/projects/12345/query/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "TrendsQuery",
    "series": [
      {
        "kind": "EventsNode",
        "event": "purchase_completed"
      }
    ],
    "dateRange": {
      "date_from": "-30d"
    },
    "breakdownFilter": {
      "breakdown_type": "event",
      "breakdown": "product_category"
    },
    "interval": "day"
  }'

import posthog

posthog.project_api_key = 'YOUR_API_KEY'

result = posthog.post('/api/projects/12345/query/', data={
    'kind': 'TrendsQuery',
    'series': [
        {
            'kind': 'EventsNode',
            'event': 'purchase_completed'
        }
    ],
    'dateRange': {
        'date_from': '-30d'
    },
    'breakdownFilter': {
        'breakdown_type': 'event',
        'breakdown': 'product_category'
    },
    'interval': 'day'
})

for series in result['results']:
    print(f"{series['label']}: {series['count']} purchases")

const response = await fetch('https://app.posthog.com/api/projects/12345/query/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    kind: 'TrendsQuery',
    series: [
      {
        kind: 'EventsNode',
        event: 'purchase_completed'
      }
    ],
    dateRange: {
      date_from: '-30d'
    },
    breakdownFilter: {
      breakdown_type: 'event',
      breakdown: 'product_category'
    },
    interval: 'day'
  })
});

const result = await response.json();
result.results.forEach(series => {
  console.log(`${series.label}: ${series.count} purchases`);
});

Response Examples

Trends Query Response

{
  "results": [
    {
      "action": {
        "id": "$pageview",
        "type": "events",
        "order": 0,
        "name": "$pageview",
        "custom_name": null
      },
      "label": "$pageview",
      "count": 15234,
      "data": [1820, 2103, 2456, 2187, 2034, 2289, 2345],
      "labels": ["15-Jan-2024", "16-Jan-2024", "17-Jan-2024", "18-Jan-2024", "19-Jan-2024", "20-Jan-2024", "21-Jan-2024"],
      "days": ["2024-01-15", "2024-01-16", "2024-01-17", "2024-01-18", "2024-01-19", "2024-01-20", "2024-01-21"]
    }
  ],
  "hasMore": false,
  "last_refresh": "2024-01-21T15:30:00Z",
  "is_cached": true,
  "timezone": "UTC",
  "query_status": {
    "complete": true,
    "error": false
  },
  "timings": [
    {
      "k": "query_execution",
      "t": 0.123
    }
  ]
}

Funnel Query Response

{
  "results": [
    {
      "name": "Started Signup",
      "count": 5420,
      "order": 0,
      "conversion_rate": 100.0
    },
    {
      "name": "Completed Signup",
      "count": 3254,
      "order": 1,
      "conversion_rate": 60.04,
      "average_conversion_time": 324.5
    }
  ],
  "is_cached": false,
  "last_refresh": "2024-01-21T15:30:00Z",
  "timezone": "UTC",
  "query_status": {
    "complete": true,
    "error": false
  }
}

HogQL Query Response

{
  "results": [
    ["$pageview", 15234],
    ["signup_completed", 3254],
    ["purchase_completed", 1847],
    ["add_to_cart", 4521],
    ["user_login", 8932]
  ],
  "columns": ["event", "count"],
  "types": ["String", "UInt64"],
  "hogql": "SELECT event, count() as count FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY event ORDER BY count DESC LIMIT 10",
  "hasMore": false,
  "is_cached": false,
  "last_refresh": "2024-01-21T15:30:00Z"
}

Error Responses

error

Invalid query structure

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

error

Invalid or missing API key

error

Insufficient permissions to query data

error

Rate limit exceeded

{
  "detail": "Request was throttled. Expected available in 42 seconds."
}

error

Query execution error

{
  "query_status": {
    "error": true,
    "error_message": "Query timeout after 60 seconds"
  }
}

Notes

Queries are executed against your ClickHouse analytics database
Results are cached for performance; use refresh parameter to control caching behavior
Use force_cache for fastest responses (may return cache miss if no cached results)
Use blocking to ensure fresh results while maintaining synchronous response
Use async for expensive queries to avoid timeouts
Query execution is subject to rate limits
HogQL queries must be read-only (SELECT statements only)
Results are automatically formatted based on query type
Aggregate queries (count, sum, etc.) return numeric results
Time-series queries return arrays of data points

Overview

Events

Feature Flags

Cohorts

Insights

Query Insights

Query Insights

Endpoint

Path Parameters

Query Parameters

Request Body

Trends Query

Funnels Query

HogQL Query

Response Fields

Examples

Trends Query

Funnel Query

HogQL Query

Query with Breakdown

Response Examples

Trends Query Response

Funnel Query Response

HogQL Query Response

Error Responses

Notes

​Query Insights

​Endpoint

​Path Parameters

​Query Parameters

​Request Body

​Trends Query

​Funnels Query

​HogQL Query

​Response Fields

​Examples

​Trends Query

​Funnel Query

​HogQL Query

​Query with Breakdown

​Response Examples

​Trends Query Response

​Funnel Query Response

​HogQL Query Response

​Error Responses

​Notes

Query Insights

Endpoint

Path Parameters

Query Parameters

Request Body

Trends Query

Funnels Query

HogQL Query

Response Fields

Examples

Trends Query

Funnel Query

HogQL Query

Query with Breakdown

Response Examples

Trends Query Response

Funnel Query Response

HogQL Query Response

Error Responses

Notes