PostHog · Schema
QueryRequest
A/B TestingAnalyticsFeature FlagsOpen SourceProduct AnalyticsSession Recording
Properties
| Name | Type | Description |
|---|---|---|
| async | boolean | |
| client_query_id | string | Client provided query ID. Can be used to retrieve the status or cancel the query. |
| filters_override | object | |
| limit_context | object | Limit context for the query. Only 'posthog_ai' is allowed as a client-provided value. |
| name | string | Name given to a query. It's used to identify the query in the UI. Up to 128 characters for a name. |
| query | object | Submit a JSON string representing a query for PostHog data analysis, for example a HogQL query. Example payload: ``` {"query": {"kind": "HogQLQuery", "query": "select * from events limit 100"}} ``` Fo |
| refresh | object | Whether results should be calculated sync or async, and how much to rely on the cache: - `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh res |
| variables_override | object |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "#/components/schemas/QueryRequest",
"title": "QueryRequest",
"additionalProperties": false,
"properties": {
"async": {
"default": null,
"title": "Async",
"type": "boolean",
"nullable": true
},
"client_query_id": {
"default": null,
"description": "Client provided query ID. Can be used to retrieve the status or cancel the query.",
"title": "Client Query Id",
"type": "string",
"nullable": true
},
"filters_override": {
"default": null,
"allOf": [
{
"$ref": "#/components/schemas/DashboardFilter"
}
],
"nullable": true
},
"limit_context": {
"default": null,
"description": "Limit context for the query. Only 'posthog_ai' is allowed as a client-provided value.",
"allOf": [
{
"$ref": "#/components/schemas/LimitContext"
}
],
"nullable": true
},
"name": {
"default": null,
"description": "Name given to a query. It's used to identify the query in the UI. Up to 128 characters for a name.",
"title": "Name",
"type": "string",
"nullable": true
},
"query": {
"description": "Submit a JSON string representing a query for PostHog data analysis, for example a HogQL query.\n\nExample payload:\n\n```\n\n{\"query\": {\"kind\": \"HogQLQuery\", \"query\": \"select * from events limit 100\"}}\n\n```\n\nFor more details on HogQL queries, see the [PostHog HogQL documentation](/docs/hogql#api-access).",
"discriminator": {
"mapping": {
"ActionsNode": "#/components/schemas/ActionsNode",
"ActorsPropertyTaxonomyQuery": "#/components/schemas/ActorsPropertyTaxonomyQuery",
"ActorsQuery": "#/components/schemas/ActorsQuery",
"DataTableNode": "#/components/schemas/DataTableNode",
"DataVisualizationNode": "#/components/schemas/DataVisualizationNode",
"DataWarehouseNode": "#/components/schemas/DataWarehouseNode",
"DatabaseSchemaQuery": "#/components/schemas/DatabaseSchemaQuery",
"DocumentSimilarityQuery": "#/components/schemas/DocumentSimilarityQuery",
"EndpointsUsageOverviewQuery": "#/components/schemas/EndpointsUsageOverviewQuery",
"EndpointsUsageTableQuery": "#/components/schemas/EndpointsUsageTableQuery",
"EndpointsUsageTrendsQuery": "#/components/schemas/EndpointsUsageTrendsQuery",
"ErrorTrackingBreakdownsQuery": "#/components/schemas/ErrorTrackingBreakdownsQuery",
"ErrorTrackingIssueCorrelationQuery": "#/components/schemas/ErrorTrackingIssueCorrelationQuery",
"ErrorTrackingQuery": "#/components/schemas/ErrorTrackingQuery",
"ErrorTrackingSimilarIssuesQuery": "#/components/schemas/ErrorTrackingSimilarIssuesQuery",
"EventTaxonomyQuery": "#/components/schemas/EventTaxonomyQuery",
"EventsNode": "#/components/schemas/EventsNode",
"EventsQuery": "#/components/schemas/EventsQuery",
"ExperimentExposureQuery": "#/components/schemas/ExperimentExposureQuery",
"ExperimentFunnelsQuery": "#/components/schemas/ExperimentFunnelsQuery",
"ExperimentQuery": "#/components/schemas/ExperimentQuery",
"ExperimentTrendsQuery": "#/components/schemas/ExperimentTrendsQuery",
"FunnelCorrelationQuery": "#/components/schemas/FunnelCorrelationQuery",
"FunnelsDataWarehouseNode": "#/components/schemas/FunnelsDataWarehouseNode",
"FunnelsQuery": "#/components/schemas/FunnelsQuery",
"GroupsQuery": "#/components/schemas/GroupsQuery",
"HogQLAutocomplete": "#/components/schemas/HogQLAutocomplete",
"HogQLMetadata": "#/components/schemas/HogQLMetadata",
"HogQLQuery": "#/components/schemas/HogQLQuery",
"HogQuery": "#/components/schemas/HogQuery",
"InsightActorsQuery": "#/components/schemas/InsightActorsQuery",
"InsightActorsQueryOptions": "#/components/schemas/InsightActorsQueryOptions",
"InsightVizNode": "#/components/schemas/InsightVizNode",
"LifecycleDataWarehouseNode": "#/components/schemas/LifecycleDataWarehouseNode",
"LifecycleQuery": "#/components/schemas/LifecycleQuery",
"LogAttributesQuery": "#/components/schemas/LogAttributesQuery",
"LogValuesQuery": "#/components/schemas/LogValuesQuery",
"LogsQuery": "#/components/schemas/LogsQuery",
"MarketingAnalyticsAggregatedQuery": "#/components/schemas/MarketingAnalyticsAggregatedQuery",
"MarketingAnalyticsTableQuery": "#/components/schemas/MarketingAnalyticsTableQuery",
"NonIntegratedConversionsTableQuery": "#/components/schemas/NonIntegratedConversionsTableQuery",
"PathsQuery": "#/components/schemas/PathsQuery",
"PersonsNode": "#/components/schemas/PersonsNode",
"PropertyValuesQuery": "#/components/schemas/PropertyValuesQuery",
"RecordingsQuery": "#/components/schemas/RecordingsQuery",
"RetentionQuery": "#/components/schemas/RetentionQuery",
"RevenueAnalyticsGrossRevenueQuery": "#/components/schemas/RevenueAnalyticsGrossRevenueQuery",
"RevenueAnalyticsMRRQuery": "#/components/schemas/RevenueAnalyticsMRRQuery",
"RevenueAnalyticsMetricsQuery": "#/components/schemas/RevenueAnalyticsMetricsQuery",
"RevenueAnalyticsOverviewQuery": "#/components/schemas/RevenueAnalyticsOverviewQuery",
"RevenueAnalyticsTopCustomersQuery": "#/components/schemas/RevenueAnalyticsTopCustomersQuery",
"RevenueExampleDataWarehouseTablesQuery": "#/components/schemas/RevenueExampleDataWarehouseTablesQuery",
"RevenueExampleEventsQuery": "#/components/schemas/RevenueExampleEventsQuery",
"SavedInsightNode": "#/components/schemas/SavedInsightNode",
"SessionAttributionExplorerQuery": "#/components/schemas/SessionAttributionExplorerQuery",
"SessionsQuery": "#/components/schemas/SessionsQuery",
"SessionsTimelineQuery": "#/components/schemas/SessionsTimelineQuery",
"StickinessQuery": "#/components/schemas/StickinessQuery",
"SuggestedQuestionsQuery": "#/components/schemas/SuggestedQuestionsQuery",
"TeamTaxonomyQuery": "#/components/schemas/TeamTaxonomyQuery",
"TraceNeighborsQuery": "#/components/schemas/TraceNeighborsQuery",
"TraceQuery": "#/components/schemas/TraceQuery",
"TraceSpansQuery": "#/components/schemas/TraceSpansQuery",
"TracesQuery": "#/components/schemas/TracesQuery",
"TrendsQuery": "#/components/schemas/TrendsQuery",
"UsageMetricsQuery": "#/components/schemas/UsageMetricsQuery",
"VectorSearchQuery": "#/components/schemas/VectorSearchQuery",
"WebAnalyticsExternalSummaryQuery": "#/components/schemas/WebAnalyticsExternalSummaryQuery",
"WebExternalClicksTableQuery": "#/components/schemas/WebExternalClicksTableQuery",
"WebGoalsQuery": "#/components/schemas/WebGoalsQuery",
"WebNotableChangesQuery": "#/components/schemas/WebNotableChangesQuery",
"WebOverviewQuery": "#/components/schemas/WebOverviewQuery",
"WebPageURLSearchQuery": "#/components/schemas/WebPageURLSearchQuery",
"WebStatsTableQuery": "#/components/schemas/WebStatsTableQuery",
"WebVitalsPathBreakdownQuery": "#/components/schemas/WebVitalsPathBreakdownQuery",
"WebVitalsQuery": "#/components/schemas/WebVitalsQuery"
},
"propertyName": "kind"
},
"oneOf": [
{
"$ref": "#/components/schemas/EventsNode"
},
{
"$ref": "#/components/schemas/ActionsNode"
},
{
"$ref": "#/components/schemas/PersonsNode"
},
{
"$ref": "#/components/schemas/DataWarehouseNode"
},
{
"$ref": "#/components/schemas/FunnelsDataWarehouseNode"
},
{
"$ref": "#/components/schemas/LifecycleDataWarehouseNode"
},
{
"$ref": "#/components/schemas/EventsQuery"
},
{
"$ref": "#/components/schemas/SessionsQuery"
},
{
"$ref": "#/components/schemas/ActorsQuery"
},
{
"$ref": "#/components/schemas/GroupsQuery"
},
{
"$ref": "#/components/schemas/InsightActorsQuery"
},
{
"$ref": "#/components/schemas/InsightActorsQueryOptions"
},
{
"$ref": "#/components/schemas/SessionsTimelineQuery"
},
{
"$ref": "#/components/schemas/HogQuery"
},
{
"$ref": "#/components/schemas/HogQLQuery"
},
{
"$ref": "#/components/schemas/HogQLMetadata"
},
{
"$ref": "#/components/schemas/HogQLAutocomplete"
},
{
"$ref": "#/components/schemas/SessionAttributionExplorerQuery"
},
{
"$ref": "#/components/schemas/RevenueExampleEventsQuery"
},
{
"$ref": "#/components/schemas/RevenueExampleDataWarehouseTablesQuery"
},
{
"$ref": "#/components/schemas/ErrorTrackingQuery"
},
{
"$ref": "#/components/schemas/ErrorTrackingSimilarIssuesQuery"
},
{
"$ref": "#/components/schemas/ErrorTrackingBreakdownsQuery"
},
{
"$ref": "#/components/schemas/ErrorTrackingIssueCorrelationQuery"
},
{
"$ref": "#/components/schemas/ExperimentFunnelsQuery"
},
{
"$ref": "#/components/schemas/ExperimentTrendsQuery"
},
{
"$ref": "#/components/schemas/ExperimentQuery"
},
{
"$ref": "#/components/schemas/ExperimentExposureQuery"
},
{
"$ref": "#/components/schemas/DocumentSimilarityQuery"
},
{
"$ref": "#/components/schemas/WebOverviewQuery"
},
{
"$ref": "#/components/schemas/WebStatsTableQuery"
},
{
"$ref": "#/components/schemas/WebExternalClicksTableQuery"
},
{
"$ref": "#/components/schemas/WebGoalsQuery"
},
{
"$ref": "#/components/schemas/WebVitalsQuery"
},
{
"$ref": "#/components/schemas/WebVitalsPathBreakdownQuery"
},
{
"$ref": "#/components/schemas/WebPageURLSearchQuery"
},
{
"$ref": "#/components/schemas/WebAnalyticsExternalSummaryQuery"
},
{
"$ref": "#/components/schemas/WebNotableChangesQuery"
},
{
"$ref": "#/components/schemas/RevenueAnalyticsGrossRevenueQuery"
},
{
"$ref": "#/components/schemas/RevenueAnalyticsMetricsQuery"
},
{
"$ref": "#/components/schemas/RevenueAnalyticsMRRQuery"
},
{
"$ref": "#/components/schemas/RevenueAnalyticsOverviewQuery"
},
{
"$ref": "#/components/schemas/RevenueAnalyticsTopCustomersQuery"
},
{
"$ref": "#/components/schemas/MarketingAnalyticsTableQuery"
},
{
"$ref": "#/components/schemas/MarketingAnalyticsAggregatedQuery"
},
{
"$ref": "#/components/schemas/NonIntegratedConversionsTableQuery"
},
{
"$ref": "#/components/schemas/DataVisualizationNode"
},
{
"$ref": "#/components/schemas/DataTableNode"
},
{
"$ref": "#/components/schemas/SavedInsightNode"
},
{
"$ref": "#/components/schemas/InsightVizNode"
},
{
"$ref": "#/components/schemas/TrendsQuery"
},
{
"$ref": "#/components/schemas/FunnelsQuery"
},
{
"$ref": "#/components/schemas/RetentionQuery"
},
{
"$ref": "#/components/schemas/PathsQuery"
},
{
"$ref": "#/components/schemas/StickinessQuery"
},
{
"$ref": "#/components/schemas/LifecycleQuery"
},
{
"$ref": "#/components/schemas/FunnelCorrelationQuery"
},
{
"$ref": "#/components/schemas/DatabaseSchemaQuery"
},
{
"$ref": "#/components/schemas/RecordingsQuery"
},
{
"$ref": "#/components/schemas/LogsQuery"
},
{
"$ref": "#/components/schemas/LogAttributesQuery"
},
{
"$ref": "#/components/schemas/LogValuesQuery"
},
{
"$ref": "#/components/schemas/TraceSpansQuery"
},
{
"$ref": "#/components/schemas/SuggestedQuestionsQuery"
},
{
"$ref": "#/components/schemas/TeamTaxonomyQuery"
},
{
"$ref": "#/components/schemas/EventTaxonomyQuery"
},
{
"$ref": "#/components/schemas/ActorsPropertyTaxonomyQuery"
},
{
"$ref": "#/components/schemas/TracesQuery"
},
{
"$ref": "#/components/schemas/TraceQuery"
},
{
"$ref": "#/components/schemas/TraceNeighborsQuery"
},
{
"$ref": "#/components/schemas/VectorSearchQuery"
},
{
"$ref": "#/components/schemas/UsageMetricsQuery"
},
{
"$ref": "#/components/schemas/EndpointsUsageOverviewQuery"
},
{
"$ref": "#/components/schemas/EndpointsUsageTableQuery"
},
{
"$ref": "#/components/schemas/EndpointsUsageTrendsQuery"
},
{
"$ref": "#/components/schemas/PropertyValuesQuery"
}
],
"title": "Query"
},
"refresh": {
"default": "blocking",
"description": "Whether results should be calculated sync or async, and how much to rely on the cache:\n- `'blocking'` - calculate synchronously (returning only when the query is done), UNLESS there are very fresh results in the cache\n- `'async'` - kick off background calculation (returning immediately with a query status), UNLESS there are very fresh results in the cache\n- `'lazy_async'` - kick off background calculation, UNLESS there are somewhat fresh results in the cache\n- `'force_blocking'` - calculate synchronously, even if fresh results are already cached\n- `'force_async'` - kick off background calculation, even if fresh results are already cached\n- `'force_cache'` - return cached data or a cache miss; always completes immediately as it never calculates Background calculation can be tracked using the `query_status` response field.",
"allOf": [
{
"$ref": "#/components/schemas/RefreshType"
}
],
"nullable": true
},
"variables_override": {
"default": null,
"title": "Variables Override",
"additionalProperties": {
"additionalProperties": true,
"type": "object"
},
"type": "object",
"nullable": true
}
},
"required": [
"query"
],
"type": "object"
}