--- title: "POST /api/projects/{project_id}/insights/data_checks/" method: POST path: "/api/projects/{project_id}/insights/data_checks/" tags: ["insights"] --- # POST /api/projects/{project_id}/insights/data_checks/ `POST /api/projects/{project_id}/insights/data_checks/` ## Request - Base URL: `https://us.posthog.com` - URL: `https://us.posthog.com/api/projects/{project_id}/insights/data_checks/` - Auth: HTTP bearer Check the events behind an insight for the common ways they mislead: internal and test users, local development traffic, bots and crawlers, and events sent twice. Works for trends, funnels, stickiness and lifecycle insights whose series are events. The checks apply the insight's own filters, and read the newest days of its date range, up to 7. The bot and duplicate checks read a sample of those days. For a token, the internal users check matches the emails of the organization's members only with the `organization_member:read` scope, and its verified domains only with `organization:read`. It names the emails it finds only with `person:read`. Nothing is stored. This route runs the query it is sent, so it needs query access as well as insight access. To check a saved insight by its id, send a GET request to `insights/{id}/data_checks/`. ## Path parameters - `project_id` string, required ## Query parameters - `format` 'csv' | 'json' ## Request body - InsightDataChecksRequest - `query` union, 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 - `BIVisualizationNode` — business intelligence worksheets with a HogQL source - `DataTableNode` — raw data tables - `HogQuery` — Hog language queries - InsightVizNode - `embedded` boolean, nullable: Query is embedded inside another bordered component - `full` boolean, nullable: Show with most visual options enabled. Used in insight scene. - `hidePersonsModal` boolean, nullable - `hideTooltipOnScroll` boolean, nullable - `kind` 'InsightVizNode' - `showCorrelationTable` boolean, nullable - `showFilters` boolean, nullable - `showHeader` boolean, nullable - `showLastComputation` boolean, nullable - `showLastComputationRefresh` boolean, nullable - `showResults` boolean, nullable - `showTable` boolean, nullable - `source` union, required - TrendsQuery - `aggregation_group_type_index` integer, nullable: Groups aggregation - `breakdownFilter` BreakdownFilter - `breakdown` union - … - `breakdown_group_type_index` integer, nullable - `breakdown_hide_other_aggregation` boolean, nullable - `breakdown_histogram_bin_count` integer, nullable - `breakdown_limit` integer, nullable - `breakdown_normalize_url` boolean, nullable - `breakdown_path_cleaning` boolean, nullable - `breakdown_type` 'cohort' | 'person' | 'event' | 'event_metadata' | 'element' | 'group' | 'session' | 'hogql' | 'data_warehouse' | 'data_warehouse_person_property' | 'revenue_analytics' - `breakdowns` Breakdown[], nullable - … - `calendarHeatmapFilter` CalendarHeatmapFilter - `bucketBySessionStart` boolean, nullable: When true and the series math is `dau`/`unique_users`, each user contributes to the (day-of-week, hour) bucket of their session's first event only — matching the web overview session-start attribution. When false (default), the user contributes to every bucket they have any event in. No effect on `total` math (event counts are unchanged either way). - `compareFilter` CompareFilter - `compare` boolean, nullable: Whether to compare the current date range to a previous date range. - `compare_to` string, nullable: The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. - `conversionGoal` union: Whether we should be comparing against a specific conversion goal - ActionConversionGoal - … - CustomEventConversionGoal - … - `dataColorTheme` number, nullable: Colors used in the insight's visualization - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `filterTestAccounts` boolean, nullable: Exclude internal and test users by applying the respective filters - `interval` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' - `kind` 'TrendsQuery' - `marketingAnalyticsCostFallback` MarketingAnalyticsCostFallback - `series` DataWarehouseNode[], required - … - `sourceIds` string[], required - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `properties` union: Property filters for all series - union[] - … - PropertyGroupFilter - … - `response` TrendsQueryResponse - `boxplot_data` BoxPlotDatum[], nullable - … - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hasMore` boolean, nullable: Wether more breakdown values are available. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` object[], required - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `samplingFactor` number, nullable: Sampling rate - `series` union[], required: Events and actions to include - union - … - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `trendsFilter` TrendsFilter - `aggregationAxisFormat` 'numeric' | 'duration' | 'duration_ms' | 'duration_ns' | 'percentage' | 'percentage_scaled' | 'currency' | 'short' - `aggregationAxisPostfix` string, nullable: Literal suffix applied to every value (e.g. ` req`). Reserve for units that `aggregationAxisFormat` cannot express. Do not use ` mins`, ` s`, ` ms`, `%` etc. — pick the matching `aggregationAxisFormat` instead so the underlying values stay numerically correct for breakdowns, formulas, and alerts. Include any leading space yourself. - `aggregationAxisPrefix` string, nullable: Literal prefix applied to every value (e.g. `$`). Use to pin a unit or currency symbol that does not depend on `aggregationAxisFormat` — for example, when values are denominated in a fixed currency regardless of the project's base currency. Include any trailing space yourself. - `annotationsScope` 'dashboard_item' | 'dashboard' | 'project' | 'organization' - `breakdown_histogram_bin_count` number, nullable - `chartStyle` ChartStyle - … - `confidenceLevel` number, nullable - `decimalPlaces` number, nullable: Maximum number of decimal places shown. 1 or 2 is usually right for percentages and currency. - `detailedResultsAggregationType` 'total' | 'average' | 'median' - `display` 'Auto' | 'ActionsLineGraph' | 'ActionsBar' | 'ActionsUnstackedBar' | 'ActionsStackedBar' | 'ActionsAreaGraph' | 'ActionsLineGraphCumulative' | 'BoldNumber' | 'Metric' | 'ActionsPie' | 'ActionsDonut' | 'ActionsProportionBar' | 'ActionsBarValue' | 'ActionsTable' | 'WorldMap' | 'CalendarHeatmap' | 'TwoDimensionalHeatmap' | 'BoxPlot' | 'SlopeGraph' | 'ScatterPlot' - `excludeBoxPlotOutliers` boolean, nullable - `formula` string, nullable - `formulaNodes` TrendsFormulaNode[], nullable: List of formulas with optional custom names. Takes precedence over formula/formulas if set. - … - `formulas` string[], nullable - `goalLines` GoalLine[], nullable: Goal Lines - … - `hiddenLegendIndexes` integer[], nullable - `hideWeekends` boolean, nullable: Ignored. Superseded by `dateRange.daysOfWeek`, which excludes the days from the query instead of only hiding their buckets. Still accepted so existing API clients keep working. - `legendPosition` 'top' | 'bottom' | 'left' | 'right' - `metricChangeDecreaseColor` string, nullable: Metric display: change pill color when the metric decreased. Defaults to red. - `metricChangeIncreaseColor` string, nullable: Metric display: change pill color when the metric increased. Defaults to green. - `metricColorByDirection` boolean, nullable: Metric display: color the sparkline by whether the metric increased or decreased. - `metricLineDecreaseColor` string, nullable: Metric display: line color when the metric decreased. Defaults to red. - `metricLineIncreaseColor` string, nullable: Metric display: line color when the metric increased. Defaults to green. - `metricShowChange` boolean, nullable: Show the period-over-period change pill on the Metric display. - `metricSummary` 'total' | 'average' | 'latest' - `minDecimalPlaces` number, nullable - `movingAverageIntervals` number, nullable - `resultCustomizationBy` 'value' | 'position' - `resultCustomizations` union: Customizations for the appearance of result datasets. - … - `showAlertThresholdLines` boolean, nullable - `showAnnotations` boolean, nullable - `showConfidenceIntervals` boolean, nullable - `showLabelsOnSeries` boolean, nullable - `showLegend` boolean, nullable - `showMovingAverage` boolean, nullable - `showMultipleYAxes` boolean, nullable - `showPercentStackView` boolean, nullable - `showTrendLines` boolean, nullable - `showValuesOnSeries` boolean, nullable - `smoothingIntervals` integer, nullable - `stackBreakdownValues` boolean, nullable: On the horizontal bar-value chart, stack a series' breakdown values into a single bar instead of rendering one bar per breakdown value. - `xAxisLabel` string, nullable: Custom label rendered under the X axis. - `yAxisLabel` string, nullable: Custom label rendered alongside the Y axis. - `yAxisMax` number, nullable: Pins the top of the y-axis; unset means automatic. Ignored in the same cases as `yAxisStartAtZero`, and when `yAxisMin` is not below it. - `yAxisMin` number, nullable: Pins the bottom of the y-axis; unset means automatic. Ignored in the same cases as `yAxisStartAtZero`, while it is on, and when not below `yAxisMax`. - `yAxisScaleType` 'log10' | 'linear' - `yAxisStartAtZero` boolean, nullable: Y-axis baseline. When false the axis floats to the data range instead of starting at zero. Ignored on bar displays (bars always draw from zero), on a logarithmic scale, and while showing percentages. - `version` number, nullable: version of the node, used for schema migrations - FunnelsQuery - `aggregation_group_type_index` integer, nullable: Groups aggregation - `breakdownFilter` BreakdownFilter - `breakdown` union - … - `breakdown_group_type_index` integer, nullable - `breakdown_hide_other_aggregation` boolean, nullable - `breakdown_histogram_bin_count` integer, nullable - `breakdown_limit` integer, nullable - `breakdown_normalize_url` boolean, nullable - `breakdown_path_cleaning` boolean, nullable - `breakdown_type` 'cohort' | 'person' | 'event' | 'event_metadata' | 'element' | 'group' | 'session' | 'hogql' | 'data_warehouse' | 'data_warehouse_person_property' | 'revenue_analytics' - `breakdowns` Breakdown[], nullable - … - `compareFilter` CompareFilter - `compare` boolean, nullable: Whether to compare the current date range to a previous date range. - `compare_to` string, nullable: The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. - `dataColorTheme` number, nullable: Colors used in the insight's visualization - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `filterTestAccounts` boolean, nullable: Exclude internal and test users by applying the respective filters - `funnelsFilter` FunnelsFilter - `annotationsScope` 'dashboard_item' | 'dashboard' | 'project' | 'organization' - `binCount` integer, nullable - `breakdownAttributionType` 'first_touch' | 'last_touch' | 'all_events' | 'step' - `breakdownAttributionValue` integer, nullable - `breakdownSorting` string, nullable: Breakdown table sorting. Format: 'column_key' or '-column_key' (descending) - `chartStyle` ChartStyle - … - `customAggregationTarget` boolean, nullable: For data warehouse based funnel insights when the aggregation target can't be mapped to persons or groups. - `exclusions` union[], nullable - … - `funnelAggregateByHogQL` string, nullable - `funnelFromStep` integer, nullable - `funnelOrderType` 'strict' | 'unordered' | 'ordered' - `funnelStepReference` 'total' | 'previous' - `funnelToStep` integer, nullable: To select the range of steps for trends & time to convert funnels, 0-indexed - `funnelVizType` 'steps' | 'time_to_convert' | 'trends' | 'flow' - `funnelWindowInterval` integer, nullable - `funnelWindowIntervalUnit` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' - `goalLines` GoalLine[], nullable: Goal Lines - … - `hiddenLegendBreakdowns` string[], nullable - `hideIncompleteConversionWindowPeriods` boolean, nullable: Trends only: hide periods whose conversion window has not fully elapsed yet, so the recent tail of the trend isn't dragged down by entrants who still have time to convert. - `layout` 'horizontal' | 'vertical' - `legendPosition` 'top' | 'bottom' | 'left' | 'right' - `resultCustomizations` object, nullable: Customizations for the appearance of result datasets. - `showAnnotations` boolean, nullable: Whether to render annotations on the chart. Only applies to historical-trends funnels. - `showLegend` boolean, nullable: Whether to show a legend describing the series. The legend only renders when the funnel has multiple series. Only applies to historical-trends funnels. - `showTrendLines` boolean, nullable: Display linear regression trend lines on the chart (only for historical trends viz) - `showValuesOnSeries` boolean, nullable - `useUdf` boolean, nullable - `interval` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' - `kind` 'FunnelsQuery' - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `properties` union: Property filters for all series - union[] - … - PropertyGroupFilter - … - `response` FunnelsQueryResponse - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` unknown, required - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `total_median_conversion_time` number, nullable: Median total conversion time across all completers, computed breakdown-agnostically for the Steps viz header. - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `samplingFactor` number, nullable: Sampling rate - `series` union[], required: Events and actions to include - union - … - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `version` number, nullable: version of the node, used for schema migrations - RetentionQuery - `aggregation_group_type_index` integer, nullable: Groups aggregation - `breakdownFilter` BreakdownFilter - `breakdown` union - … - `breakdown_group_type_index` integer, nullable - `breakdown_hide_other_aggregation` boolean, nullable - `breakdown_histogram_bin_count` integer, nullable - `breakdown_limit` integer, nullable - `breakdown_normalize_url` boolean, nullable - `breakdown_path_cleaning` boolean, nullable - `breakdown_type` 'cohort' | 'person' | 'event' | 'event_metadata' | 'element' | 'group' | 'session' | 'hogql' | 'data_warehouse' | 'data_warehouse_person_property' | 'revenue_analytics' - `breakdowns` Breakdown[], nullable - … - `dataColorTheme` number, nullable: Colors used in the insight's visualization - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `filterTestAccounts` boolean, nullable: Exclude internal and test users by applying the respective filters - `kind` 'RetentionQuery' - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `properties` union: Property filters for all series - union[] - … - PropertyGroupFilter - … - `response` RetentionQueryResponse - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` RetentionResult[], required - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `retentionFilter` RetentionFilter, required - `aggregationProperty` string, nullable: The property to aggregate when aggregationType is sum or avg - `aggregationPropertyType` 'event' | 'person' | 'data_warehouse' - `aggregationType` 'count' | 'sum' | 'avg' - `chartStyle` ChartStyle - … - `cohortLabelStartIndex` integer, nullable: Starting index used when labeling cohort columns (e.g. 0 for D0/D1/D2, 1 for D1/D2/D3). Display-only — does not affect retention calculations. - `cumulative` boolean, nullable - `customAggregationTarget` boolean, nullable: For data warehouse based retention insights when the aggregation target can't be mapped to persons or groups. - `dashboardDisplay` 'table_only' | 'graph_only' | 'all' - `display` 'Auto' | 'ActionsLineGraph' | 'ActionsBar' | 'ActionsUnstackedBar' | 'ActionsStackedBar' | 'ActionsAreaGraph' | 'ActionsLineGraphCumulative' | 'BoldNumber' | 'Metric' | 'ActionsPie' | 'ActionsDonut' | 'ActionsProportionBar' | 'ActionsBarValue' | 'ActionsTable' | 'WorldMap' | 'CalendarHeatmap' | 'TwoDimensionalHeatmap' | 'BoxPlot' | 'SlopeGraph' | 'ScatterPlot' - `goalLines` GoalLine[], nullable - … - `meanRetentionCalculation` 'simple' | 'weighted' | 'none' - `minimumOccurrences` integer, nullable - `period` 'Hour' | 'Day' | 'Week' | 'Month' - `retentionCustomBrackets` number[], nullable: Custom brackets for retention calculations - `retentionReference` 'total' | 'previous' - `retentionType` 'retention_recurring' | 'retention_first_time' | 'retention_first_ever_occurrence' - `returningEntity` RetentionEntity - … - `selectedInterval` integer, nullable: The selected interval to display across all cohorts (null = show all intervals for each cohort) - `showMeanLine` boolean, nullable: Draw the mean across cohorts as one line on the retention graph. - `showTrendLines` boolean, nullable - `targetEntity` RetentionEntity - … - `timeWindowMode` 'strict_calendar_dates' | '24_hour_windows' - `totalIntervals` integer, nullable - `samplingFactor` number, nullable: Sampling rate - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `version` number, nullable: version of the node, used for schema migrations - PathsQuery - `aggregation_group_type_index` integer, nullable: Groups aggregation - `dataColorTheme` number, nullable: Colors used in the insight's visualization - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `filterTestAccounts` boolean, nullable: Exclude internal and test users by applying the respective filters - `funnelPathsFilter` FunnelPathsFilter - `funnelPathType` 'funnel_path_before_step' | 'funnel_path_between_steps' | 'funnel_path_after_step' - `funnelSource` FunnelsQuery, required - … - `funnelStep` integer, nullable - `kind` 'PathsQuery' - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `pathsFilter` PathsFilter, required - `edgeLimit` integer, nullable - `endPoint` string, nullable - `excludeEvents` string[], nullable - `includeEventTypes` PathType[], nullable - `localPathCleaningFilters` PathCleaningFilter[], nullable - … - `maxEdgeWeight` integer, nullable - `minEdgeWeight` integer, nullable - `pathDropoffKey` string, nullable: Relevant only within actors query - `pathEndKey` string, nullable: Relevant only within actors query - `pathGroupings` string[], nullable - `pathReplacements` boolean, nullable - `pathStartKey` string, nullable: Relevant only within actors query - `pathsHogQLExpression` string, nullable - `showFullUrls` boolean, nullable - `startPoint` string, nullable - `stepLimit` integer, nullable - `stripQueryString` boolean, nullable: Remove the query string from page view URLs, so pages that differ only in query parameters become one path item - `properties` union: Property filters for all series - union[] - … - PropertyGroupFilter - … - `response` PathsQueryResponse - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` PathsLink[], required - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `samplingFactor` number, nullable: Sampling rate - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `version` number, nullable: version of the node, used for schema migrations - PathsV2Query - `dataColorTheme` number, nullable: Colors used in the insight's visualization - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `filterTestAccounts` boolean, nullable: Exclude internal and test users by applying the respective filters - `kind` 'PathsV2Query' - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `pathsV2Filter` PathsV2Filter - `anchor` PathsV2Anchor - … - `applyTeamPathCleaning` boolean, nullable: Apply the team's path cleaning rules to naming property values before they become path items. - `collapseRepeats` boolean, nullable: Merge immediate repeats of the same path item within a journey. - `conversionWindowInterval` integer, nullable: Anchored mode's single conversion window W, anchored at the anchor and reused verbatim as the emitted funnel's window. Bounds per unit are validated server-side against CONVERSION_WINDOW_INTERVAL_BOUNDS, the same funnel conversion window bounds as the gap. - `conversionWindowIntervalUnit` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' - `excludedItems` PathsV2Item[], nullable: Path items dropped from the item universe: events deriving to one of these items are ignored as if their event were not a step source, on both the paths side and the "view as funnel" side. - … - `gapInterval` integer, nullable: Inactivity gap that splits an actor's events into journeys. Bounds per unit are validated server-side against CONVERSION_WINDOW_INTERVAL_BOUNDS, the funnel conversion window bounds. - `gapIntervalUnit` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' - `localPathCleaningFilters` PathCleaningFilter[], nullable: Path cleaning rules for this insight only, applied after the team's rules. - … - `maxRowsPerStep` integer, nullable: Number of path item rows per step; items beyond this go into the "other" row. - `maxSteps` integer, nullable: Number of journey steps (columns) shown. - `stepSources` PathsV2StepSource[], nullable: Step sources defining which events can become path items. Defaults to the pageviews preset: `$pageview` named by `$pathname`. - … - `properties` union: Property filters for all series - union[] - … - PropertyGroupFilter - … - `response` PathsV2QueryResponse - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` PathsV2Results, required - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `version` number, nullable: version of the node, used for schema migrations - StickinessQuery - `compareFilter` CompareFilter - `compare` boolean, nullable: Whether to compare the current date range to a previous date range. - `compare_to` string, nullable: The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. - `dataColorTheme` number, nullable: Colors used in the insight's visualization - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `filterTestAccounts` boolean, nullable: Exclude internal and test users by applying the respective filters - `interval` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' - `intervalCount` integer, nullable: How many intervals comprise a period. Only used for cohorts, otherwise default 1. - `kind` 'StickinessQuery' - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `properties` union: Property filters for all series - union[] - … - PropertyGroupFilter - … - `response` StickinessQueryResponse - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` object[], required - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `samplingFactor` number, nullable: Sampling rate - `series` union[], required: Events and actions to include - union - … - `stickinessFilter` StickinessFilter - `chartStyle` ChartStyle - … - `computedAs` 'non_cumulative' | 'cumulative' - `display` 'Auto' | 'ActionsLineGraph' | 'ActionsBar' | 'ActionsUnstackedBar' | 'ActionsStackedBar' | 'ActionsAreaGraph' | 'ActionsLineGraphCumulative' | 'BoldNumber' | 'Metric' | 'ActionsPie' | 'ActionsDonut' | 'ActionsProportionBar' | 'ActionsBarValue' | 'ActionsTable' | 'WorldMap' | 'CalendarHeatmap' | 'TwoDimensionalHeatmap' | 'BoxPlot' | 'SlopeGraph' | 'ScatterPlot' - `hiddenLegendIndexes` integer[], nullable - `legendPosition` 'top' | 'bottom' | 'left' | 'right' - `resultCustomizationBy` 'value' | 'position' - `resultCustomizations` union: Customizations for the appearance of result datasets. - … - `showLegend` boolean, nullable - `showMultipleYAxes` boolean, nullable - `showValuesOnSeries` boolean, nullable - `stickinessCriteria` StickinessCriteria - … - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `version` number, nullable: version of the node, used for schema migrations - LifecycleQuery - `aggregation_group_type_index` integer, nullable: Groups aggregation - `customAggregationTarget` boolean, nullable: For data warehouse based lifecycle insights when the aggregation target can't be mapped to persons or groups. - `dataColorTheme` number, nullable: Colors used in the insight's visualization - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `filterTestAccounts` boolean, nullable: Exclude internal and test users by applying the respective filters - `interval` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' - `kind` 'LifecycleQuery' - `lifecycleFilter` LifecycleFilter - `legendPosition` 'top' | 'bottom' | 'left' | 'right' - `showLegend` boolean, nullable - `showPercentagesOnSeries` boolean, nullable: Append per-band percentage to each value label (e.g. `580 (42%)`). Requires `showValuesOnSeries` — on its own it has no visible effect. - `showValuesOnSeries` boolean, nullable - `stacked` boolean, nullable - `toggledLifecycles` LifecycleToggle[], nullable - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `properties` union: Property filters for all series - union[] - … - PropertyGroupFilter - … - `response` LifecycleQueryResponse - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` object[], required - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `samplingFactor` number, nullable: Sampling rate - `series` union[], required: Events and actions to include - union - … - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `version` number, nullable: version of the node, used for schema migrations - WebStatsTableQuery - `aggregation_group_type_index` integer, nullable: Groups aggregation - not used in Web Analytics but required for type compatibility - `breakdownBy` 'Page' | 'InitialPage' | 'ExitPage' | 'ExitClick' | 'PreviousPage' | 'ScreenName' | 'InitialChannelType' | 'InitialReferringDomain' | 'InitialReferringURL' | 'InitialUTMSource' | 'InitialUTMCampaign' | 'InitialUTMMedium' | 'InitialUTMTerm' | 'InitialUTMContent' | 'InitialUTMSourceMediumCampaign' | 'FirstPageviewChannelType' | 'FirstPageviewReferringDomain' | 'FirstPageviewUTMSource' | 'FirstPageviewUTMCampaign' | 'FirstPageviewUTMMedium' | 'FirstPageviewUTMTerm' | 'FirstPageviewUTMContent' | 'FirstPageviewUTMSourceMediumCampaign' | 'Browser' | 'InAppBrowser' | 'OS' | 'Viewport' | 'DeviceType' | 'Country' | 'Region' | 'City' | 'Timezone' | 'Language' | 'FrustrationMetrics', required - `compareFilter` CompareFilter - `compare` boolean, nullable: Whether to compare the current date range to a previous date range. - `compare_to` string, nullable: The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. - `conversionGoal` union - ActionConversionGoal - … - CustomEventConversionGoal - … - `dataColorTheme` number, nullable: Colors used in the insight's visualization - not used in Web Analytics but required for type compatibility - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `doPathCleaning` boolean, nullable - `filterTestAccounts` boolean, nullable - `includeAvgTimeOnPage` boolean, nullable - `includeBounceRate` boolean, nullable - `includeHost` boolean, nullable - `includeRevenue` boolean, nullable - `includeScrollDepth` boolean, nullable - `includeTrafficMetrics` boolean, nullable - `interval` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' - `kind` 'WebStatsTableQuery' - `limit` integer, nullable - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `offset` integer, nullable - `orderBy` union[], nullable - union - … - `properties` union[], required - union - … - `response` WebStatsTableQueryResponse - `columns` unknown[], nullable - … - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hasMore` boolean, nullable - `hogql` string, nullable: Generated HogQL query. - `limit` integer, nullable - `modifiers` HogQLQueryModifiers - … - `offset` integer, nullable - `preComputeIneligibleReason` string, nullable: Why a live response skipped precompute: the eligibility-gate reason that refused it. Unset when the query was eligible. - `preComputeStale` boolean, nullable: Whether a lazy-precompute read was served from expired-within-grace (stale) jobs instead of recomputing inline. - `preComputeStrategy` 'pre_aggregated' | 'lazy_precompute' | 'live' - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` unknown[], required - … - `samplingRate` SamplingRate - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `types` unknown[], nullable - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `sampling` WebAnalyticsSampling - `enabled` boolean, nullable - `forceSamplingRate` SamplingRate - … - `samplingFactor` number, nullable: Sampling rate - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `useSessionsTable` boolean, nullable - `useWebAnalyticsPrecompute` boolean, nullable: Opt this specific query into the web stats table precompute path. Requires the `web-analytics-precompute-toggle` PostHog feature flag to be on for the team's organization for the gate to pass. * - `version` number, nullable: version of the node, used for schema migrations - WebOverviewQuery - `aggregation_group_type_index` integer, nullable: Groups aggregation - not used in Web Analytics but required for type compatibility - `compareFilter` CompareFilter - `compare` boolean, nullable: Whether to compare the current date range to a previous date range. - `compare_to` string, nullable: The date range to compare to. The value is a relative date. Examples of relative dates are: `-1y` for 1 year ago, `-14m` for 14 months ago, `-100w` for 100 weeks ago, `-14d` for 14 days ago, `-30h` for 30 hours ago. - `conversionGoal` union - ActionConversionGoal - … - CustomEventConversionGoal - … - `dataColorTheme` number, nullable: Colors used in the insight's visualization - not used in Web Analytics but required for type compatibility - `dateRange` DateRange - `date_from` string, nullable: Start of the date range. Accepts ISO 8601 timestamps (e.g., 2024-01-15T00:00:00Z) or relative formats: -7d (7 days ago), -2w (2 weeks ago), -1m (1 month ago), -1h (1 hour ago), -1mStart (start of last month), -1yStart (start of last year). - `date_to` string, nullable: End of the date range. Same format as date_from. Omit or null for "now". A calendar day without a time (2024-01-15) is inclusive: it rounds to the last moment of that day in the project timezone, unless explicitDate is set. - `daysOfWeek` DaysOfWeekEnum[], nullable: Restrict the query to events occurring on these ISO days of week (1=Monday to 7=Sunday), evaluated in the project timezone. Omit or empty for all days. Only applied by insight queries. - `excludeIncompletePeriods` boolean, nullable: Exclude the current, still-collecting period by clipping date_to to the end of the last complete interval (evaluated in the project timezone). No-op when the range contains no complete interval. Only applied by insight queries. - `explicitDate` boolean, nullable: Whether the date_from and date_to should be used verbatim. Disables rounding to the start and end of period. - `doPathCleaning` boolean, nullable - `filterTestAccounts` boolean, nullable - `includeRevenue` boolean, nullable - `interval` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' - `kind` 'WebOverviewQuery' - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `orderBy` union[], nullable - union - … - `properties` union[], required - union - … - `response` WebOverviewQueryResponse - `dateFrom` string, nullable - `dateTo` string, nullable - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - … - `preComputeIneligibleReason` string, nullable: Why a live response skipped precompute: the eligibility-gate reason that refused it. Unset when the query was eligible. - `preComputeStrategy` 'pre_aggregated' | 'lazy_precompute' | 'live' - `query_status` QueryStatus - … - `resolved_compare_date_range` ResolvedDateRangeResponse - … - `resolved_date_range` ResolvedDateRangeResponse - … - `results` WebOverviewItem[], required - … - `samplingRate` SamplingRate - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - … - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - … - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - … - `sampling` WebAnalyticsSampling - `enabled` boolean, nullable - `forceSamplingRate` SamplingRate - … - `samplingFactor` number, nullable: Sampling rate - `tags` QueryLogTags - `name` string, nullable: Name of the query, preferably unique. For example web_analytics_vitals - `presetId` string, nullable: Short id of the saved Web analytics filter preset this query was run under, if any. - `productKey` string, nullable: Product responsible for this query. Use string, there's no need to churn the Schema when we add a new product * - `scene` string, nullable: Scene where this query is shown in the UI. Use string, there's no need to churn the Schema when we add a new Scene * - `useSessionsTable` boolean, nullable - `useWebAnalyticsPrecompute` boolean, nullable: Opt this specific query into the web_overview_query precompute path. Requires the `web-analytics-precompute-toggle` PostHog feature flag to be on for the team's organization for the gate to pass. * - `version` number, nullable: version of the node, used for schema migrations - `suppressSessionAnalysisWarning` boolean, nullable - `version` number, nullable: version of the node, used for schema migrations - `vizSpecificOptions` VizSpecificOptions - `ActionsPie` ActionsPie - `disableHoverOffset` boolean, nullable - `hideAggregation` boolean, nullable - `RETENTION` RETENTION - `hideLineGraph` boolean, nullable - `hideSizeColumn` boolean, nullable - `useSmallLayout` boolean, nullable - DataTableNode - `allowSorting` boolean, nullable: Can the user click on column headers to sort the table? (default: true) - `columns` string[], nullable: Columns shown in the table, unless the `source` provides them. - `context` DataTableNodeViewPropsContext - `eventDefinitionId` string, nullable - `type` 'event_definition' | 'team_columns', required - `contextKey` string, nullable: Context key for universal column configuration (e.g., "survey:123") - `defaultColumns` string[], nullable: Default columns to use when resetting column configuration - `embedded` boolean, nullable: Uses the embedded version of LemonTable - `expandable` boolean, nullable: Can expand row to show raw event data (default: true) - `full` boolean, nullable: Show with most visual options enabled. Used in scenes. - `hiddenColumns` string[], nullable: Columns that aren't shown in the table, even if in columns or returned data - `kind` 'DataTableNode' - `pinnedColumns` string[], nullable: Columns that are sticky when scrolling horizontally - `propertiesViaUrl` boolean, nullable: Link properties via the URL (default: false) - `response` union - object - Response - `columns` unknown[], required - unknown - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hasMore` boolean, nullable - `hogql` string, required: Generated HogQL query. - `limit` integer, nullable - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `nextCursor` string, nullable: Cursor for fetching the next page of results - `offset` integer, nullable - `query_status` QueryStatus - `budget_remaining_bytes` integer, nullable - `bytes_read` integer, nullable - `cache_key` string, nullable: Cache key of the run that failed, so clients can ask for its query scan. - `complete` boolean, nullable: Whether the query is still running. Will be true if the query is complete, even if it errored. Either result or error will be set. - `dashboard_id` integer, nullable - `end_time` string, date-time, nullable: When did the query execution task finish (whether successfully or not). - `error` boolean, nullable: If the query failed, this will be set to true. More information can be found in the error_message field. - `error_code` string, nullable: Stable machine-readable code for the error, when known: the DRF exception code, the ClickHouse error name, the HogQL error code, or `unhandled_` for a failure that no handler classified. - `error_message` string, nullable - `expiration_time` string, date-time, nullable - `id` string, required - `insight_id` integer, nullable - `labels` string[], nullable - `pickup_time` string, date-time, nullable: When was the query execution task picked up by a worker. - `query_async` true: ONLY async queries use QueryStatus. - `query_progress` ClickhouseQueryProgress - … - `query_scan` QueryScanSummary - … - `results` unknown - `start_time` string, date-time, nullable: When was query execution task enqueued. - `task_id` string, nullable - `team_id` integer, required - `resolved_compare_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `resolved_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `results` array[], required - unknown[] - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - `k` string, required: Key. Shortened to 'k' to save on data. - `t` number, required: Time in seconds. Shortened to 't' to save on data. - `types` string[], required - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - `id` string, required: ExternalDataSource id - `source_type` string, nullable: Connector type of the source (e.g. Stripe, Postgres), if known - `table_name` string, required: Warehouse table name that was referenced - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - union - … - Response1 - `columns` unknown[], required - unknown - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hasMore` boolean, nullable - `hogql` string, required: Generated HogQL query. - `limit` integer, required - `missing_actors_count` integer, nullable - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `offset` integer, required - `query_status` QueryStatus - `budget_remaining_bytes` integer, nullable - `bytes_read` integer, nullable - `cache_key` string, nullable: Cache key of the run that failed, so clients can ask for its query scan. - `complete` boolean, nullable: Whether the query is still running. Will be true if the query is complete, even if it errored. Either result or error will be set. - `dashboard_id` integer, nullable - `end_time` string, date-time, nullable: When did the query execution task finish (whether successfully or not). - `error` boolean, nullable: If the query failed, this will be set to true. More information can be found in the error_message field. - `error_code` string, nullable: Stable machine-readable code for the error, when known: the DRF exception code, the ClickHouse error name, the HogQL error code, or `unhandled_` for a failure that no handler classified. - `error_message` string, nullable - `expiration_time` string, date-time, nullable - `id` string, required - `insight_id` integer, nullable - `labels` string[], nullable - `pickup_time` string, date-time, nullable: When was the query execution task picked up by a worker. - `query_async` true: ONLY async queries use QueryStatus. - `query_progress` ClickhouseQueryProgress - … - `query_scan` QueryScanSummary - … - `results` unknown - `start_time` string, date-time, nullable: When was query execution task enqueued. - `task_id` string, nullable - `team_id` integer, required - `resolved_compare_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `resolved_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `results` array[], required - unknown[] - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - `k` string, required: Key. Shortened to 'k' to save on data. - `t` number, required: Time in seconds. Shortened to 't' to save on data. - `types` string[], nullable - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - `id` string, required: ExternalDataSource id - `source_type` string, nullable: Connector type of the source (e.g. Stripe, Postgres), if known - `table_name` string, required: Warehouse table name that was referenced - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - union - … - Response2 - `columns` unknown[], required - unknown - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hasMore` boolean, nullable - `hogql` string, required: Generated HogQL query. - `kind` 'GroupsQuery' - `limit` integer, required - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `offset` integer, required - `query_status` QueryStatus - `budget_remaining_bytes` integer, nullable - `bytes_read` integer, nullable - `cache_key` string, nullable: Cache key of the run that failed, so clients can ask for its query scan. - `complete` boolean, nullable: Whether the query is still running. Will be true if the query is complete, even if it errored. Either result or error will be set. - `dashboard_id` integer, nullable - `end_time` string, date-time, nullable: When did the query execution task finish (whether successfully or not). - `error` boolean, nullable: If the query failed, this will be set to true. More information can be found in the error_message field. - `error_code` string, nullable: Stable machine-readable code for the error, when known: the DRF exception code, the ClickHouse error name, the HogQL error code, or `unhandled_` for a failure that no handler classified. - `error_message` string, nullable - `expiration_time` string, date-time, nullable - `id` string, required - `insight_id` integer, nullable - `labels` string[], nullable - `pickup_time` string, date-time, nullable: When was the query execution task picked up by a worker. - `query_async` true: ONLY async queries use QueryStatus. - `query_progress` ClickhouseQueryProgress - … - `query_scan` QueryScanSummary - … - `results` unknown - `start_time` string, date-time, nullable: When was query execution task enqueued. - `task_id` string, nullable - `team_id` integer, required - `resolved_compare_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `resolved_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `results` array[], required - unknown[] - … - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - `k` string, required: Key. Shortened to 'k' to save on data. - `t` number, required: Time in seconds. Shortened to 't' to save on data. - `types` string[], required - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - `id` string, required: ExternalDataSource id - `source_type` string, nullable: Connector type of the source (e.g. Stripe, Postgres), if known - `table_name` string, required: Warehouse table name that was referenced - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - union - … - Response3 - `clickhouse` string, nullable: Executed ClickHouse query - `column_formats` string[], nullable: Display formats for directly selected virtual properties, aligned with columns. - `columns` unknown[], nullable: Returned columns - unknown - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `explain` string[], nullable: Query explanation output - `hasMore` boolean, nullable - `hogql` string, nullable: Generated HogQL query. - `limit` integer, nullable - `metadata` HogQLMetadataResponse - `ch_table_names` string[], nullable - `errors` HogQLNotice[], required - … - `index_usage` PredicateIndexUsage[], nullable: One entry per property filter, in query order. - … - `isUsingIndices` 'undecisive' | 'no' | 'partial' | 'yes' - `isValid` boolean, nullable - `notices` HogQLNotice[], required - … - `output_columns` HogQLMetadataColumn[], nullable: Best-effort output schema, without executing the query. Only included when includeOutputTypes is requested and inference succeeds. - … - `query` string, nullable - `table_names` string[], nullable - `warnings` HogQLNotice[], required - … - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `offset` integer, nullable - `query` string, nullable: Input query string - `query_status` QueryStatus - `budget_remaining_bytes` integer, nullable - `bytes_read` integer, nullable - `cache_key` string, nullable: Cache key of the run that failed, so clients can ask for its query scan. - `complete` boolean, nullable: Whether the query is still running. Will be true if the query is complete, even if it errored. Either result or error will be set. - `dashboard_id` integer, nullable - `end_time` string, date-time, nullable: When did the query execution task finish (whether successfully or not). - `error` boolean, nullable: If the query failed, this will be set to true. More information can be found in the error_message field. - `error_code` string, nullable: Stable machine-readable code for the error, when known: the DRF exception code, the ClickHouse error name, the HogQL error code, or `unhandled_` for a failure that no handler classified. - `error_message` string, nullable - `expiration_time` string, date-time, nullable - `id` string, required - `insight_id` integer, nullable - `labels` string[], nullable - `pickup_time` string, date-time, nullable: When was the query execution task picked up by a worker. - `query_async` true: ONLY async queries use QueryStatus. - `query_progress` ClickhouseQueryProgress - … - `query_scan` QueryScanSummary - … - `results` unknown - `start_time` string, date-time, nullable: When was query execution task enqueued. - `task_id` string, nullable - `team_id` integer, required - `resolved_compare_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `resolved_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `results` unknown[], required - unknown - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - `k` string, required: Key. Shortened to 'k' to save on data. - `t` number, required: Time in seconds. Shortened to 't' to save on data. - `types` unknown[], nullable: Types of returned columns - unknown - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - `id` string, required: ExternalDataSource id - `source_type` string, nullable: Connector type of the source (e.g. Stripe, Postgres), if known - `table_name` string, required: Warehouse table name that was referenced - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Also carries access control warnings when a system-table query filters out objects the user can't access. - union - … - Response4 - `dateFrom` string, nullable - `dateTo` string, nullable - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hogql` string, nullable: Generated HogQL query. - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `preComputeIneligibleReason` string, nullable: Why a live response skipped precompute: the eligibility-gate reason that refused it. Unset when the query was eligible. - `preComputeStrategy` 'pre_aggregated' | 'lazy_precompute' | 'live' - `query_status` QueryStatus - `budget_remaining_bytes` integer, nullable - `bytes_read` integer, nullable - `cache_key` string, nullable: Cache key of the run that failed, so clients can ask for its query scan. - `complete` boolean, nullable: Whether the query is still running. Will be true if the query is complete, even if it errored. Either result or error will be set. - `dashboard_id` integer, nullable - `end_time` string, date-time, nullable: When did the query execution task finish (whether successfully or not). - `error` boolean, nullable: If the query failed, this will be set to true. More information can be found in the error_message field. - `error_code` string, nullable: Stable machine-readable code for the error, when known: the DRF exception code, the ClickHouse error name, the HogQL error code, or `unhandled_` for a failure that no handler classified. - `error_message` string, nullable - `expiration_time` string, date-time, nullable - `id` string, required - `insight_id` integer, nullable - `labels` string[], nullable - `pickup_time` string, date-time, nullable: When was the query execution task picked up by a worker. - `query_async` true: ONLY async queries use QueryStatus. - `query_progress` ClickhouseQueryProgress - … - `query_scan` QueryScanSummary - … - `results` unknown - `start_time` string, date-time, nullable: When was query execution task enqueued. - `task_id` string, nullable - `team_id` integer, required - `resolved_compare_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `resolved_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `results` WebOverviewItem[], required - `changeFromPreviousPct` number, nullable - `isIncreaseBad` boolean, nullable - `key` string, required - `kind` 'unit' | 'duration_s' | 'percentage' | 'currency', required - `previous` number, nullable - `value` number, nullable - `samplingRate` SamplingRate - `denominator` number, nullable - `numerator` number, required - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - `k` string, required: Key. Shortened to 'k' to save on data. - `t` number, required: Time in seconds. Shortened to 't' to save on data. - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - `id` string, required: ExternalDataSource id - `source_type` string, nullable: Connector type of the source (e.g. Stripe, Postgres), if known - `table_name` string, required: Warehouse table name that was referenced - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - union - … - Response5 - `columns` unknown[], nullable - unknown - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hasMore` boolean, nullable - `hogql` string, nullable: Generated HogQL query. - `limit` integer, nullable - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - `useNewEventsCluster` boolean, nullable: Read this query from the native events cluster and native JSON events table (`true`), or keep its existing connection (`false` or unset). This is an internal rollout switch for eligible projects. PostHog staff manage eligibility through instance settings. Each query must opt in; project defaults cannot enable it. Only synchronous HogQLQuery SQL comparisons are supported. - `useNewEventsSchema` boolean, nullable: Read events from the native JSON events table (`true`) or the legacy events table (`false`). When unset, the project's stored value applies, then the `CLICKHOUSE_HOGQL_USE_NEW_EVENTS_SCHEMA` instance settings. This is an internal rollout switch. PostHog staff set the project value in Django admin and the project settings API ignores it. - `usePreaggregatedIntermediateResults` boolean, nullable - `usePreaggregatedTableTransforms` boolean, nullable: Try to automatically convert HogQL queries to use preaggregated tables at the AST level * - `useWebAnalyticsPreAggregatedTables` boolean, nullable - `webAnalyticsFirstPageviewFilters` boolean, nullable: Serve filters on the stored session-entry attribution properties (`$channel_type`, `$entry_utm_*`, `$entry_referring_domain`) by recomputing the value from the session's first pageview. Resolved server-side; not intended to be set by clients. - `offset` integer, nullable - `preComputeIneligibleReason` string, nullable: Why a live response skipped precompute: the eligibility-gate reason that refused it. Unset when the query was eligible. - `preComputeStale` boolean, nullable: Whether a lazy-precompute read was served from expired-within-grace (stale) jobs instead of recomputing inline. - `preComputeStrategy` 'pre_aggregated' | 'lazy_precompute' | 'live' - `query_status` QueryStatus - `budget_remaining_bytes` integer, nullable - `bytes_read` integer, nullable - `cache_key` string, nullable: Cache key of the run that failed, so clients can ask for its query scan. - `complete` boolean, nullable: Whether the query is still running. Will be true if the query is complete, even if it errored. Either result or error will be set. - `dashboard_id` integer, nullable - `end_time` string, date-time, nullable: When did the query execution task finish (whether successfully or not). - `error` boolean, nullable: If the query failed, this will be set to true. More information can be found in the error_message field. - `error_code` string, nullable: Stable machine-readable code for the error, when known: the DRF exception code, the ClickHouse error name, the HogQL error code, or `unhandled_` for a failure that no handler classified. - `error_message` string, nullable - `expiration_time` string, date-time, nullable - `id` string, required - `insight_id` integer, nullable - `labels` string[], nullable - `pickup_time` string, date-time, nullable: When was the query execution task picked up by a worker. - `query_async` true: ONLY async queries use QueryStatus. - `query_progress` ClickhouseQueryProgress - … - `query_scan` QueryScanSummary - … - `results` unknown - `start_time` string, date-time, nullable: When was query execution task enqueued. - `task_id` string, nullable - `team_id` integer, required - `resolved_compare_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `resolved_date_range` ResolvedDateRangeResponse - `date_from` string, date-time, required - `date_to` string, date-time, required - `results` unknown[], required - unknown - `samplingRate` SamplingRate - `denominator` number, nullable - `numerator` number, required - `timings` QueryTiming[], nullable: Measured timings for different parts of the query generation process - `k` string, required: Key. Shortened to 'k' to save on data. - `t` number, required: Time in seconds. Shortened to 't' to save on data. - `types` unknown[], nullable - unknown - `used_data_warehouse_sources` DataWarehouseSourceUsage[], nullable: Connector-synced data warehouse sources referenced by this query, if any. - `id` string, required: ExternalDataSource id - `source_type` string, nullable: Connector type of the source (e.g. Stripe, Postgres), if known - `table_name` string, required: Warehouse table name that was referenced - `warnings` union[], nullable: Warnings about data warehouse sources referenced by the query whose latest sync failed, is paused, hit a billing limit, or is otherwise stale. Results may not reflect current source data. Accumulated across every HogQL execution that contributes to this response — so insights backed by warehouse tables (Trends, Funnels, etc.) receive the same warnings as raw HogQL queries. Also carries access control warnings when a system-table query filters out objects the user can't access. - union - … - Response6 - `columns` unknown[], nullable - unknown - `error` string, nullable: Query error. Returned only if 'explain' or `modifiers.debug` is true. Throws an error otherwise. - `hasMore` boolean, nullable - `hogql` string, nullable: Generated HogQL query. - `limit` integer, nullable - `modifiers` HogQLQueryModifiers - `bounceRateDurationSeconds` number, nullable - `bounceRatePageViewMode` 'count_pageviews' | 'uniq_urls' | 'uniq_page_screen_autocaptures' - `convertToProjectTimezone` boolean, nullable - `cookielessTrafficIsRegular` boolean, nullable: Do not treat a missing user agent as automation on cookieless events. Positive bot signals and custom project rules still apply. Resolved server-side; not intended to be set by clients. - `customBotDefinitions` CustomBotRule[], nullable - … - `customChannelTypeRules` CustomChannelRule[], nullable - … - `dataWarehouseEventsModifiers` DataWarehouseEventsModifier[], nullable - … - `debug` boolean, nullable - `forceClickhouseDataSkippingIndexes` string[], nullable: If these are provided, the query will fail if these skip indexes are not used - `formatCsvAllowDoubleQuotes` boolean, nullable - `inCohortVia` 'auto' | 'leftjoin' | 'subquery' | 'leftjoin_conjoined' - `inlineCohortCalculation` 'off' | 'auto' | 'always' - `materializationMode` 'auto' | 'legacy_null_as_string' | 'legacy_null_as_null' | 'disabled' - `materializedColumnsOptimizationMode` 'disabled' | 'optimized' - `mergeFederatedAggregateJoins` boolean, nullable: Merge sibling aggregating LEFT JOINs over federated Postgres tables into one UNION ALL join, so their scans overlap - `negatedPersonFiltersNotIn` boolean, nullable: Replace negated person-property filters in the WHERE of an `events` query (such as `email not_icontains`) with `person_id NOT IN (SELECT id FROM persons WHERE )`, so the query no longer joins every person. Applies only when every filtered person property has a materialized column, nothing else in the query reads that persons join, and the join would be a LEFT JOIN. - `optimizeJoinedFilters` boolean, nullable - `optimizeProjections` boolean, nullable - `parserMode` 'cpp_only' | 'cpp_with_rust_shadow' | 'cpp_with_rust_py_shadow' | 'rust_with_cpp_shadow' | 'rust_only' | 'rust_py_only' | 'rust_py_with_cpp_shadow' - `personIdPushdown` boolean, nullable: Push an `id IN (SELECT person_id FROM WHERE …)` predicate into the joined persons subquery, so the latest-version lookup only reads persons that the outer query's left-table filters can reach. Applies only to a persons join from the query's own FROM table. - `personsArgMaxVersion` 'auto' | 'v1' | 'v2' - `personsJoinMode` 'inner' | 'left' - `personsOnEventsMode` 'disabled' | 'person_id_no_override_properties_on_events' | 'person_id_override_properties_on_events' | 'person_id_override_properties_joined' - `propertyGroupsMode` 'enabled' | 'disabled' | 'optimized' - `pushDownPredicates` boolean, nullable - `s3TableUseInvalidColumns` boolean, nullable - `sessionIdPushdown` boolean, nullable: Push a `session_id_v7 IN (SELECT … FROM events WHERE …)` predicate into the raw_sessions subquery to limit aggregation to sessions that participate in the outer events filter. - `sessionPropertyPreAggregation` boolean, nullable: Pre-filter raw_sessions aggregation by `session_id_v7 IN (cheap pre-aggregation that only materializes the columns referenced by the outer-WHERE session predicate)`. Useful when the breakdown/SELECT pulls in many session columns (e.g. `$channel_type`) but the filter only references one (e.g. `$entry_current_url`). - `sessionTableVersion` 'auto' | 'v1' | 'v2' | 'v3' - `sessionTimestampBufferMinutes` integer, nullable: Padding, in minutes, on each side of the event time range when it filters the sessions table by session start. Defaults to 3 days. It can only narrow the range: values above the default are ignored. Lower it only for a query that keeps just the sessions that start inside its own time range. - `sessionsV2JoinMode` 'string' | 'uuid' - `timings` boolean, nullable - `typeAwareCastSimplification` boolean, nullable: Remove provably redundant casts and nullability wrappers (e.g. `toString(String)`, `assumeNotNull(non_nullable)`, dead `ifNull` fallbacks) using inferred expression types - `useMaterializedViews` boolean, nullable - … truncated; see the full OpenAPI document linked below ## Response `200` The result of every check. - InsightDataChecks - `status` 'passed' | 'warning' | 'problem' | 'partial' | 'on_request' | 'no_events' | 'unsupported' | 'inconclusive', required: * `passed` - No data issues found * `warning` - A check found a small issue * `problem` - A check found a large issue * `partial` - Some checks could not run, and the others found no issue * `on_request` - The checks would read a lot of data, so they run only on request * `no_events` - No events to check * `unsupported` - This kind of insight cannot be checked * `inconclusive` - No check could run - `checks` InsightDataCheck[], required: Every check, in a fixed order, whatever its result. - `key` 'internal_users' | 'local_development' | 'bot_traffic' | 'duplicate_events', required: * `internal_users` - Internal and test users * `local_development` - Local development events * `bot_traffic` - Bot and crawler traffic * `duplicate_events` - Events sent twice - `level` 'passed' | 'warning' | 'problem' | 'skipped', required: * `passed` - Passed * `warning` - Warning * `problem` - Problem * `skipped` - Not checked - `skip_reason` union, required: Why the check did not run. Null unless `level` is `skipped`. * `too_many_events` - The days checked hold too many events to count * `read_limit` - The check would read more data than it is allowed * `time_limit` - The check took longer than it is allowed * `memory_limit` - The check needed more memory than it is allowed * `too_few_sampled_events` - The sample has too few events to give a share * `filtered_by_traffic_type` - The insight already filters on traffic type * `hidden_property` - A property the check reads is hidden from you * `invalid_filter` - The project's internal and test users filter cannot run * `on_request` - The check would read a lot of data, so it runs only on request - 'too_many_events' | 'read_limit' | 'time_limit' | 'memory_limit' | 'too_few_sampled_events' | 'filtered_by_traffic_type' | 'hidden_property' | 'invalid_filter' | 'on_request': * `too_many_events` - The days checked hold too many events to count * `read_limit` - The check would read more data than it is allowed * `time_limit` - The check took longer than it is allowed * `memory_limit` - The check needed more memory than it is allowed * `too_few_sampled_events` - The sample has too few events to give a share * `filtered_by_traffic_type` - The insight already filters on traffic type * `hidden_property` - A property the check reads is hidden from you * `invalid_filter` - The project's internal and test users filter cannot run * `on_request` - The check would read a lot of data, so it runs only on request - unknown - `method` union, required: `counted` when the check counted every event on the days checked, `sampled` when it read a sample. Null when the check did not run. * `counted` - Counted every event on the days checked * `sampled` - Checked a sample of the events on the days checked - 'counted' | 'sampled': * `counted` - Counted every event on the days checked * `sampled` - Checked a sample of the events on the days checked - unknown - `events` integer, nullable, required: How many events on the days checked the check found. Null when the check did not run. - `share` number, double, nullable, required: `events` as a share of the events checked, from 0 to 1. Null when the check did not run, or when the sample is too small to give a share. - `scaled` boolean, required: True when `events` is an estimate scaled up from a sample, rather than a count of every event. - `action` union, required: The change that fixes it. `filter_internal_users`: set `filterTestAccounts` to true on the insight's query. `open_filter_settings`: change the project's internal and test users filter, for example by adding `filter_to_add`. Null when there is no single change. * `filter_internal_users` - Turn on the internal and test users filter for the insight * `open_filter_settings` - Change the project's internal and test users filter - 'filter_internal_users' | 'open_filter_settings': * `filter_internal_users` - Turn on the internal and test users filter for the insight * `open_filter_settings` - Change the project's internal and test users filter - unknown - `top_events` string[], required: The event names the check found most often, most affected first. - `top_hosts` string[], required: For the local development check, the local hosts whose events the project's internal and test users filter keeps, most affected first. - `distinct_hosts` integer, nullable, required: For the local development check, how many local hosts sent the events in `events`. Null for the other checks and when the check did not run. - `top_bots` string[], required: For the bot traffic check, the bots and crawlers found most often, most affected first. - `distinct_bots` integer, nullable, required: For the bot traffic check, how many named bots and crawlers sent the sampled events. Null for the other checks and when the check did not run. - `removed_by_filter` integer, nullable, required: For the internal users check, the part of `events` that the project's internal and test users filter removes. It is 0 when the insight already applies the filter. Null for the other checks and when the check did not run. - `missed_by_filter` integer, nullable, required: For the internal users check, the part of `events` from team emails that the project's internal and test users filter keeps. Null for the other checks and when the check did not run. - `top_emails` string[], required: For the internal users check, the team emails whose events the project's internal and test users filter keeps, most affected first. Only emails the caller may see as the team's are matched. Empty for a token without the `person:read` scope. - `distinct_emails` integer, nullable, required: For the internal users check, how many team emails sent events that the project's internal and test users filter keeps. Null for the other checks and when the check did not run. - `filter_to_add` InsightDataCheckFilter, required - `key` string, required: The property the rule reads, such as `$host`. - `type` string, required: The kind of property, such as `event` or `person`. - `operator` string, required: How the rule compares the property, such as `not_regex`. - `value` string[], required: The values the rule compares the property to. - `coverage` InsightDataChecksCoverage, required - `date_from` string, date, required: The first day of the insight's date range. - `date_to` string, date, required: The last day of the insight's date range. - `days_in_range` integer, required: How many days the insight's date range holds. - `checked_date_from` string, date, required: The first day the checks read. - `checked_date_to` string, date, required: The last day the checks read. - `days_checked` integer, required: How many days the checks read. The checks read the newest days of the range, up to 7. - `filters_test_accounts` boolean, required: True when the insight filters out the project's internal and test users. - `events_checked` integer, nullable, required: How many events the insight reads on the days checked. Counted exactly, or scaled up from the sample when the days hold too many events to count. Null when neither ran. - `sample` InsightDataChecksSample, required - `rate` number, double, required: The share of the events on the days checked that the sample read, from 0 to 1. - `events` integer, required: How many events the sample read. - `distinct_ids` integer, required: How many distinct IDs sent the events the sample read. ## Changes > 53 revisions in range; 1 not diffed. - **2026-10-22** `417e6bbbc890`: 6 warning, 1 info - added the new `on_request` enum value to the `checks/items/skip_reason/oneOf[#/components/schemas/InsightDataCheckSkipReasonEnum]/` response property for the response status `200` (media type: application/json) - added the new `on_request` enum value to the `checks/items/skip_reason/oneOf[#/components/schemas/InsightDataCheckSkipReasonEnum]/` response property for the response status `200` (media type: text/csv) - added the new `on_request` enum value to the `status/allOf[#/components/schemas/InsightDataChecksStatusEnum]/` response property for the response status `200` (media type: application/json) - added the new `on_request` enum value to the `status/allOf[#/components/schemas/InsightDataChecksStatusEnum]/` response property for the response status `200` (media type: text/csv) - …3 more - **2026-10-22** `0ca22e1eb92b`: 1 info - added `#/components/schemas/AccountUsersQuery` to the `query/allOf[subschema #1: _InsightQuerySchema]/oneOf[subschema #2: DataTableNode]/source/oneOf[subschema #4: ActorsQuery]/source` request property `anyOf` list - …earlier changes not shown [Operation history](https://skmtc.dev/posthog/apis/posthog-api/changes/api/projects/:project_id/insights/data_checks/post.md) --- [API](https://skmtc.dev/posthog/apis/posthog-api.md) · [All operations](https://skmtc.dev/posthog/apis/posthog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/posthog/apis/posthog-api/revisions/993f70ab941b?raw)