:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
/**
* Auto-generated from the Django backend OpenAPI schema.
* To modify these types, update the Django serializers or views, then run:
* hogli build:openapi
* Questions or issues? #team-devex on Slack
*
* PostHog API - generated
* OpenAPI spec version: 1.0.0
*/
/**
* * `engineering` - Engineering
* * `data` - Data
* * `product` - Product Management
* * `founder` - Founder
* * `leadership` - Leadership
* * `marketing` - Marketing
* * `sales` - Sales / Success
* * `student` - Student
* * `other` - Other
*/
export type RoleAtOrganizationEnumApi = (typeof RoleAtOrganizationEnumApi)[keyof typeof RoleAtOrganizationEnumApi]
export const RoleAtOrganizationEnumApi = {
Engineering: 'engineering',
Data: 'data',
Product: 'product',
Founder: 'founder',
Leadership: 'leadership',
Marketing: 'marketing',
Sales: 'sales',
Student: 'student',
Other: 'other',
} as const
export type BlankEnumApi = (typeof BlankEnumApi)[keyof typeof BlankEnumApi]
export const BlankEnumApi = {
'': '',
} as const
/**
* @nullable
*/
export type UserBasicApiHedgehogConfig = { [key: string]: unknown } | null
export interface UserBasicApi {
readonly id: number
readonly uuid: string
/**
* @maxLength 200
* @nullable
*/
distinct_id?: string | null
/** @maxLength 150 */
first_name?: string
/** @maxLength 150 */
last_name?: string
/** @maxLength 254 */
email: string
/** @nullable */
is_email_verified?: boolean | null
/** @nullable */
readonly hedgehog_config: UserBasicApiHedgehogConfig
role_at_organization?: RoleAtOrganizationEnumApi | BlankEnumApi | null
}
/**
* Materialization status for an endpoint version.
*/
export interface EndpointMaterializationApi {
/** URL-safe endpoint name. */
name: string
/** Whether materialization is enabled for this endpoint version. */
enabled: boolean
/** Whether a successful materialization is available to serve. */
ready: boolean
/** Current materialization status (e.g. 'Completed', 'Running'). */
status?: string
/** Whether this endpoint query can be materialized. */
can_materialize: boolean
/**
* Reason why materialization is not possible (only when can_materialize is false).
* @nullable
*/
reason?: string | null
/**
* ISO 8601 timestamp of the last successful materialization.
* @nullable
*/
last_materialized_at?: string | null
/** Last materialization error message, if any. */
error?: string
/**
* UUID of the underlying saved query backing this materialization. Only populated when the version is materialized.
* @nullable
*/
saved_query_id?: string | null
}
/**
* A column in the endpoint's query result.
*/
export interface EndpointColumnApi {
/** Column name from the query SELECT clause. */
name: string
/** Serialized column type: integer, float, string, datetime, date, boolean, array, json, or unknown. */
type: string
}
/**
* Per-column bucket overrides for range variable materialization.
* @nullable
*/
export type EndpointResponseApiBucketOverrides = { [key: string]: unknown } | null
/**
* Full endpoint representation returned by list/retrieve/create/update.
*/
export interface EndpointResponseApi {
/** Unique endpoint identifier (UUID). */
id: string
/** URL-safe endpoint name, unique per team. */
name: string
/**
* Human-readable description of the endpoint.
* @nullable
*/
description: string | null
/** The HogQL or insight query definition (JSON object with 'kind' key). */
query: unknown
/** Whether the endpoint can be executed via the API. */
is_active: boolean
/** Effective data freshness, in seconds. Materialized endpoints use the node's refresh target, which can differ from the standard freshness choices. Other endpoints use the cache duration. */
data_freshness_seconds: number
/** Relative API path to execute this endpoint (e.g. /api/projects/{team_id}/endpoints/{name}/run). */
endpoint_path: string
/**
* Absolute URL to execute this endpoint.
* @nullable
*/
url: string | null
/**
* Absolute URL to view this endpoint in the PostHog UI.
* @nullable
*/
ui_url: string | null
/** When the endpoint was created (ISO 8601). */
created_at: string
/** When the endpoint was last updated (ISO 8601). */
updated_at: string
/** User who created the endpoint. */
readonly created_by: UserBasicApi
/** Whether the current version's results are pre-computed to S3. */
is_materialized: boolean
/** Latest version number. */
current_version: number
/**
* UUID of the current EndpointVersion row.
* @nullable
*/
current_version_id?: string | null
/** Total number of versions for this endpoint. */
versions_count: number
/**
* Short ID of the source insight, if derived from one.
* @nullable
*/
derived_from_insight: string | null
/**
* When this endpoint was last executed via the API (ISO 8601), or null if never executed.
* @nullable
*/
last_executed_at: string | null
/** Materialization status and configuration for the current version. */
materialization: EndpointMaterializationApi
/**
* Per-column bucket overrides for range variable materialization.
* @nullable
*/
bucket_overrides: EndpointResponseApiBucketOverrides
/** Column names and types from the query's SELECT clause. */
columns: EndpointColumnApi[]
/** Tag names associated with this endpoint. */
tags: string[]
/** Breakdown property names that may be omitted on /run. Omitted ones return data aggregated across all values of that breakdown. */
optional_breakdown_properties: string[]
}
export interface PaginatedEndpointResponseListApi {
count: number
/** @nullable */
next?: string | null
/** @nullable */
previous?: string | null
results: EndpointResponseApi[]
}
/**
* Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys.
* @nullable
*/
export type EndpointRequestApiBucketOverrides = { [key: string]: unknown } | null
/**
* Schema for creating/updating endpoints. OpenAPI docs only — validation uses Pydantic.
*/
export interface EndpointRequestApi {
/**
* Unique URL-safe name. Must start with a letter, only letters/numbers/hyphens/underscores, max 128 chars.
* @nullable
*/
name?: string | null
/** HogQL or insight query this endpoint executes. Changing this auto-creates a new version. */
query?: unknown
/**
* Human-readable description of what this endpoint returns.
* @nullable
*/
description?: string | null
/**
* How fresh the data should be, in seconds. Must be one of: 900 (15 min), 1800 (30 min), 3600 (1 h), 21600 (6 h), 43200 (12 h), 86400 (24 h, default), 604800 (7 d). Controls cache TTL and materialization sync frequency.
* @nullable
*/
data_freshness_seconds?: number | null
/**
* Whether this endpoint is available for execution via the API.
* @nullable
*/
is_active?: boolean | null
/**
* Whether query results are materialized to S3.
* @nullable
*/
is_materialized?: boolean | null
/**
* Short ID of the insight this endpoint was derived from.
* @nullable
*/
derived_from_insight?: string | null
/**
* Target a specific version for updates (defaults to current version).
* @nullable
*/
version?: number | null
/**
* Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys.
* @nullable
*/
bucket_overrides?: EndpointRequestApiBucketOverrides
/**
* Set to true to soft-delete this endpoint.
* @nullable
*/
deleted?: boolean | null
/**
* List of tag names to associate with this endpoint. Replaces any existing tags.
* @nullable
*/
tags?: string[] | null
/**
* Breakdown property names that may be omitted on /run. Omitted ones return data aggregated across all values of that breakdown. Defaults to [] — every breakdown variable is required.
* @nullable
*/
optional_breakdown_properties?: string[] | null
}
/**
* Per-column bucket overrides for range variable materialization.
* @nullable
*/
export type EndpointVersionResponseApiBucketOverrides = { [key: string]: unknown } | null
/**
* Extended endpoint representation when viewing a specific version.
*/
export interface EndpointVersionResponseApi {
/** Unique endpoint identifier (UUID). */
id: string
/** URL-safe endpoint name, unique per team. */
name: string
/**
* Human-readable description of the endpoint.
* @nullable
*/
description: string | null
/** The HogQL or insight query definition (JSON object with 'kind' key). */
query: unknown
/** Whether the endpoint can be executed via the API. */
is_active: boolean
/** Effective data freshness, in seconds. Materialized endpoints use the node's refresh target, which can differ from the standard freshness choices. Other endpoints use the cache duration. */
data_freshness_seconds: number
/** Relative API path to execute this endpoint (e.g. /api/projects/{team_id}/endpoints/{name}/run). */
endpoint_path: string
/**
* Absolute URL to execute this endpoint.
* @nullable
*/
url: string | null
/**
* Absolute URL to view this endpoint in the PostHog UI.
* @nullable
*/
ui_url: string | null
/** When the endpoint was created (ISO 8601). */
created_at: string
/** When the endpoint was last updated (ISO 8601). */
updated_at: string
/** User who created the endpoint. */
readonly created_by: UserBasicApi
/** Whether the current version's results are pre-computed to S3. */
is_materialized: boolean
/** Latest version number. */
current_version: number
/**
* UUID of the current EndpointVersion row.
* @nullable
*/
current_version_id?: string | null
/** Total number of versions for this endpoint. */
versions_count: number
/**
* Short ID of the source insight, if derived from one.
* @nullable
*/
derived_from_insight: string | null
/**
* When this specific version was last executed via the API (ISO 8601), or null if it hasn't been executed. Per-version tracking is recent, so versions that predate it read null until their next run.
* @nullable
*/
last_executed_at: string | null
/** Materialization status and configuration for the current version. */
materialization: EndpointMaterializationApi
/**
* Per-column bucket overrides for range variable materialization.
* @nullable
*/
bucket_overrides: EndpointVersionResponseApiBucketOverrides
/** Column names and types from the query's SELECT clause. */
columns: EndpointColumnApi[]
/** Tag names associated with this endpoint. */
tags: string[]
/** Breakdown property names that may be omitted on /run. Omitted ones return data aggregated across all values of that breakdown. */
optional_breakdown_properties: string[]
/** Version number. */
version: number
/** Version unique identifier (UUID). */
version_id: string
/** Whether the parent endpoint is active (distinct from version.is_active). */
endpoint_is_active: boolean
/** ISO 8601 timestamp when this version was created. */
version_created_at: string
/**
* ISO 8601 timestamp when this version was last updated.
* @nullable
*/
version_updated_at: string | null
/** User who created this version. */
readonly version_created_by: UserBasicApi | null
}
/**
* Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys.
* @nullable
*/
export type PatchedEndpointRequestApiBucketOverrides = { [key: string]: unknown } | null
/**
* Schema for creating/updating endpoints. OpenAPI docs only — validation uses Pydantic.
*/
export interface PatchedEndpointRequestApi {
/**
* Unique URL-safe name. Must start with a letter, only letters/numbers/hyphens/underscores, max 128 chars.
* @nullable
*/
name?: string | null
/** HogQL or insight query this endpoint executes. Changing this auto-creates a new version. */
query?: unknown
/**
* Human-readable description of what this endpoint returns.
* @nullable
*/
description?: string | null
/**
* How fresh the data should be, in seconds. Must be one of: 900 (15 min), 1800 (30 min), 3600 (1 h), 21600 (6 h), 43200 (12 h), 86400 (24 h, default), 604800 (7 d). Controls cache TTL and materialization sync frequency.
* @nullable
*/
data_freshness_seconds?: number | null
/**
* Whether this endpoint is available for execution via the API.
* @nullable
*/
is_active?: boolean | null
/**
* Whether query results are materialized to S3.
* @nullable
*/
is_materialized?: boolean | null
/**
* Short ID of the insight this endpoint was derived from.
* @nullable
*/
derived_from_insight?: string | null
/**
* Target a specific version for updates (defaults to current version).
* @nullable
*/
version?: number | null
/**
* Per-column bucket overrides for range variable materialization. Keys are column names, values are bucket keys.
* @nullable
*/
bucket_overrides?: PatchedEndpointRequestApiBucketOverrides
/**
* Set to true to soft-delete this endpoint.
* @nullable
*/
deleted?: boolean | null
/**
* List of tag names to associate with this endpoint. Replaces any existing tags.
* @nullable
*/
tags?: string[] | null
/**
* Breakdown property names that may be omitted on /run. Omitted ones return data aggregated across all values of that breakdown. Defaults to [] — every breakdown variable is required.
* @nullable
*/
optional_breakdown_properties?: string[] | null
}
/**
* Per-column bucket function overrides, e.g. {"timestamp": "hour"}
* @nullable
*/
export type MaterializationPreviewRequestApiBucketOverrides = { [key: string]: string } | null
export interface MaterializationPreviewRequestApi {
/** Endpoint version to preview. Defaults to the current version. */
version?: number
/**
* Per-column bucket function overrides, e.g. {"timestamp": "hour"}
* @nullable
*/
bucket_overrides?: MaterializationPreviewRequestApiBucketOverrides
}
export interface MaterializationPreviewRangePairApi {
/** Column the query buckets on. */
column: string
/** Query variables that filter on this column. */
variables: string[]
/** Bucket function applied to the column. */
bucket_fn: string
}
export interface MaterializationPreviewAggregateApi {
/** Aggregate expression in the transformed query. */
expression: string
/**
* Function that combines materialized partials again, or null when there is none.
* @nullable
*/
reaggregate_fn: string | null
}
export interface MaterializationPreviewResponseApi {
/** Whether the endpoint query can be materialized. */
can_materialize: boolean
/**
* Why the query cannot be materialized, or null when it can.
* @nullable
*/
reason: string | null
/**
* Query rewritten for materialization, when one could be produced.
* @nullable
*/
transformed_query: string | null
/**
* Query that would run against the materialized table.
* @nullable
*/
execution_query: string | null
/**
* Execution query formatted for display.
* @nullable
*/
display_execution_query: string | null
/** Bucketed columns and the variables that filter on them. */
range_pairs: MaterializationPreviewRangePairApi[]
/** Aggregate expressions and how to re-aggregate them. */
aggregates: MaterializationPreviewAggregateApi[]
}
/**
* Response from executing an endpoint query.
*/
export interface EndpointRunResponseApi {
/** URL-safe endpoint name that was executed. */
name: string
/** Unique identifier for this execution. Use it to find the matching entry in the endpoint's logs. */
execution_id?: string
/** Query result rows. Each row is a list of values matching the columns order. */
results?: unknown[]
/** Column names from the query SELECT clause. */
columns?: string[]
/** Whether more results are available beyond the limit. */
hasMore?: boolean
/** Version number of the endpoint that was executed. */
endpoint_version?: number
}
/**
* Variables to parameterize the endpoint query. The key is the variable name and the value is the variable value.
*
* For HogQL endpoints: Keys must match a variable `code_name` defined in the query (referenced as `{variables.code_name}`). Example: `{"event_name": "$pageview"}`
*
* For non-materialized insight endpoints (e.g. TrendsQuery): - `date_from` and `date_to` are built-in variables that filter the date range. Example: `{"date_from": "2024-01-01", "date_to": "2024-01-31"}`
*
* For materialized insight endpoints: - Use the breakdown property name as the key to filter by breakdown value. Example: `{"$browser": "Chrome"}` - `date_from`/`date_to` are not supported on materialized insight endpoints.
*
* Unknown variable names will return a 400 error.
*/
export type EndpointRunRequestApiVariables = { [key: string]: unknown } | null
export type BreakdownTypeApi = (typeof BreakdownTypeApi)[keyof typeof BreakdownTypeApi]
export const BreakdownTypeApi = {
Cohort: 'cohort',
Person: 'person',
Event: 'event',
EventMetadata: 'event_metadata',
Element: 'element',
Group: 'group',
Session: 'session',
Hogql: 'hogql',
DataWarehouse: 'data_warehouse',
DataWarehousePersonProperty: 'data_warehouse_person_property',
RevenueAnalytics: 'revenue_analytics',
} as const
export type MultipleBreakdownTypeApi = (typeof MultipleBreakdownTypeApi)[keyof typeof MultipleBreakdownTypeApi]
export const MultipleBreakdownTypeApi = {
Person: 'person',
Event: 'event',
EventMetadata: 'event_metadata',
Element: 'element',
Group: 'group',
Session: 'session',
Hogql: 'hogql',
Cohort: 'cohort',
RevenueAnalytics: 'revenue_analytics',
DataWarehouse: 'data_warehouse',
DataWarehousePersonProperty: 'data_warehouse_person_property',
} as const
export interface BreakdownApi {
group_type_index?: number | null
histogram_bin_count?: number | null
normalize_url?: boolean | null
property: string | number
type?: MultipleBreakdownTypeApi | null
}
export interface BreakdownFilterApi {
breakdown?: string | (string | number)[] | number | null
breakdown_group_type_index?: number | null
breakdown_hide_other_aggregation?: boolean | null
breakdown_histogram_bin_count?: number | null
breakdown_limit?: number | null
breakdown_normalize_url?: boolean | null
breakdown_path_cleaning?: boolean | null
breakdown_type?: BreakdownTypeApi | null
breakdowns?: BreakdownApi[] | null
}
export interface CompareFilterApi {
/** Whether to compare the current date range to a previous date range. */
compare?: boolean | null
/** 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. */
compare_to?: string | null
}
export type IntervalTypeApi = (typeof IntervalTypeApi)[keyof typeof IntervalTypeApi]
export const IntervalTypeApi = {
Second: 'second',
Minute: 'minute',
Hour: 'hour',
Day: 'day',
Week: 'week',
Month: 'month',
Quarter: 'quarter',
Year: 'year',
} as const
export type MetricsFilterOpApi = (typeof MetricsFilterOpApi)[keyof typeof MetricsFilterOpApi]
export const MetricsFilterOpApi = {
Eq: 'eq',
Neq: 'neq',
Regex: 'regex',
NotRegex: 'not_regex',
} as const
export type MetricsAttributeScopeApi = (typeof MetricsAttributeScopeApi)[keyof typeof MetricsAttributeScopeApi]
export const MetricsAttributeScopeApi = {
Resource: 'resource',
Attribute: 'attribute',
Auto: 'auto',
} as const
export interface MetricsQueryFilterApi {
key: string
op: MetricsFilterOpApi
scope?: MetricsAttributeScopeApi | null
value: string
}
export interface MetricsDashboardVariableSelectionApi {
all?: boolean | null
/** The selected values. Empty when `all` is true: All stands for every option of the variable. */
values: string[]
}
export type MetricsDashboardVariableSourceApi =
(typeof MetricsDashboardVariableSourceApi)[keyof typeof MetricsDashboardVariableSourceApi]
export const MetricsDashboardVariableSourceApi = {
Custom: 'custom',
Promql: 'promql',
Sql: 'sql',
Textbox: 'textbox',
} as const
export interface MetricsDashboardVariableApi {
/** The text that All puts in a PromQL query. `.*` when it is empty. */
allValue?: string | null
current?: MetricsDashboardVariableSelectionApi | null
/** The options when `source` is `custom`. */
customValues?: string[] | null
includeAll?: boolean | null
/** Shown in the dashboard filter bar. The name is shown when it is empty. */
label?: string | null
multi?: boolean | null
/** Letters, digits and underscores. Tiles refer to it as `$name`. */
name: string
/** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
query?: string | null
/** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
regex?: string | null
source: MetricsDashboardVariableSourceApi
}
export type PropertyOperatorApi = (typeof PropertyOperatorApi)[keyof typeof PropertyOperatorApi]
export const PropertyOperatorApi = {
Exact: 'exact',
IsNot: 'is_not',
Icontains: 'icontains',
NotIcontains: 'not_icontains',
StartsWith: 'starts_with',
NotStartsWith: 'not_starts_with',
EndsWith: 'ends_with',
NotEndsWith: 'not_ends_with',
Regex: 'regex',
NotRegex: 'not_regex',
Gt: 'gt',
Gte: 'gte',
Lt: 'lt',
Lte: 'lte',
IsSet: 'is_set',
IsNotSet: 'is_not_set',
IsDateExact: 'is_date_exact',
IsDateBefore: 'is_date_before',
IsDateAfter: 'is_date_after',
Between: 'between',
NotBetween: 'not_between',
Min: 'min',
Max: 'max',
In: 'in',
NotIn: 'not_in',
IsCleanedPathExact: 'is_cleaned_path_exact',
IsCleanedPathNotExact: 'is_cleaned_path_not_exact',
FlagEvaluatesTo: 'flag_evaluates_to',
SemverEq: 'semver_eq',
SemverNeq: 'semver_neq',
SemverGt: 'semver_gt',
SemverGte: 'semver_gte',
SemverLt: 'semver_lt',
SemverLte: 'semver_lte',
SemverTilde: 'semver_tilde',
SemverCaret: 'semver_caret',
SemverWildcard: 'semver_wildcard',
IcontainsMulti: 'icontains_multi',
NotIcontainsMulti: 'not_icontains_multi',
} as const
export interface EventPropertyFilterApi {
key: string
label?: string | null
operator?: PropertyOperatorApi | null
/** Event properties */
type?: 'event'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface PersonPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
/** Person properties */
type?: 'person'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface PersonMetadataPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
/** Top-level columns on the persons table (e.g. created_at), not properties JSON */
type?: 'person_metadata'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export type Key10Api = (typeof Key10Api)[keyof typeof Key10Api]
export const Key10Api = {
TagName: 'tag_name',
Text: 'text',
Href: 'href',
Selector: 'selector',
} as const
export interface ElementPropertyFilterApi {
key: Key10Api
label?: string | null
operator: PropertyOperatorApi
type?: 'element'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface EventMetadataPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'event_metadata'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface SessionPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'session'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface CohortPropertyFilterApi {
/** Set by the feature flag API when the cohort is deleted or does not exist. */
cohort_deleted?: boolean | null
/** Set by the feature flag API when the cohort does not exist, so it cannot be restored. */
cohort_missing?: boolean | null
cohort_name?: string | null
key?: 'id'
label?: string | null
operator?: PropertyOperatorApi | null
type?: 'cohort'
value: number
}
export type DurationTypeApi = (typeof DurationTypeApi)[keyof typeof DurationTypeApi]
export const DurationTypeApi = {
Duration: 'duration',
ActiveSeconds: 'active_seconds',
InactiveSeconds: 'inactive_seconds',
} as const
export interface RecordingPropertyFilterApi {
key: DurationTypeApi | string
label?: string | null
operator: PropertyOperatorApi
type?: 'recording'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface LogEntryPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'log_entry'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export type GroupPropertyFilterApiGroupKeyNames = { [key: string]: string } | null
export interface GroupPropertyFilterApi {
group_key_names?: GroupPropertyFilterApiGroupKeyNames
group_type_index?: number | null
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'group'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface FeaturePropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
/** Event property with "$feature/" prepended */
type?: 'feature'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface FlagPropertyFilterApi {
/** The key should be the flag ID */
key: string
label?: string | null
/** Only flag_evaluates_to operator is allowed for flag dependencies */
operator?: 'flag_evaluates_to'
/** Feature flag dependency */
type?: 'flag'
/** The value can be true, false, or a variant name */
value: boolean | string
}
export interface HogQLPropertyFilterApi {
key: string
label?: string | null
type?: 'hogql'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export const EmptyPropertyFilterApiValue = {
type: 'empty',
} as const
export type EmptyPropertyFilterApi = typeof EmptyPropertyFilterApiValue
export interface DataWarehousePropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'data_warehouse'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface DataWarehousePersonPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'data_warehouse_person_property'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface ErrorTrackingIssueFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'error_tracking_issue'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export type LogPropertyFilterTypeApi = (typeof LogPropertyFilterTypeApi)[keyof typeof LogPropertyFilterTypeApi]
export const LogPropertyFilterTypeApi = {
Log: 'log',
LogAttribute: 'log_attribute',
LogResourceAttribute: 'log_resource_attribute',
} as const
export interface LogPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type: LogPropertyFilterTypeApi
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface MetricPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'metric_attribute'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export type SpanPropertyFilterTypeApi = (typeof SpanPropertyFilterTypeApi)[keyof typeof SpanPropertyFilterTypeApi]
export const SpanPropertyFilterTypeApi = {
Span: 'span',
SpanAttribute: 'span_attribute',
SpanResourceAttribute: 'span_resource_attribute',
} as const
export interface SpanPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type: SpanPropertyFilterTypeApi
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface RevenueAnalyticsPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'revenue_analytics'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface AccountCustomPropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
/** Customer analytics account custom property — the key is the property definition id */
type?: 'account_custom_property'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export interface WorkflowVariablePropertyFilterApi {
key: string
label?: string | null
operator: PropertyOperatorApi
type?: 'workflow_variable'
value?: (string | number | boolean)[] | string | number | boolean | null
}
export type BehavioralEventSourceApi = (typeof BehavioralEventSourceApi)[keyof typeof BehavioralEventSourceApi]
export const BehavioralEventSourceApi = {
Events: 'events',
Actions: 'actions',
} as const
export type TimeUnitTypeApi = (typeof TimeUnitTypeApi)[keyof typeof TimeUnitTypeApi]
export const TimeUnitTypeApi = {
Day: 'day',
Week: 'week',
Month: 'month',
Year: 'year',
} as const
export type InlineBehavioralTypeApi = (typeof InlineBehavioralTypeApi)[keyof typeof InlineBehavioralTypeApi]
export const InlineBehavioralTypeApi = {
PerformedEvent: 'performed_event',
PerformedEventMultiple: 'performed_event_multiple',
} as const
export interface BehavioralPropertyFilterApi {
/** Extra property filters the matching events must satisfy. Deliberately excludes nested behavioral/cohort filters and groups */
event_filters?:
| (
| EventPropertyFilterApi
| PersonPropertyFilterApi
| ElementPropertyFilterApi
| FeaturePropertyFilterApi
| HogQLPropertyFilterApi
)[]
| null
event_type: BehavioralEventSourceApi
/** Absolute or relative (e.g. -30d) lower date bound — alternative to time_value/time_interval */
explicit_datetime?: string | null
explicit_datetime_to?: string | null
/** Event name, or action id when event_type is 'actions' */
key: string
label?: string | null
/** Match persons who did NOT satisfy the criterion. Not the same as a low count — zero-occurrence persons never match count operators */
negation?: boolean | null
/** Count comparison for performed_event_multiple, defaults to exact */
operator?: PropertyOperatorApi | null
/** Count threshold for performed_event_multiple */
operator_value?: number | null
time_interval?: TimeUnitTypeApi | null
/** Relative time window size, paired with time_interval */
time_value?: number | null
/** Person performed (or didn't perform) an event in a time window. ClickHouse-only — not evaluable by flags or CDP */
type?: 'behavioral'
value: InlineBehavioralTypeApi
}
export interface DashboardFilterApi {
breakdown_filter?: BreakdownFilterApi | null
/** Period comparison forced onto every insight that supports one. Absent/null = inherit. */
compareFilter?: CompareFilterApi | null
date_from?: string | null
date_to?: string | null
explicitDate?: boolean | null
/** Tri-state test-account override. Null/absent = inherit; true = force on; false = force off. */
filterTestAccounts?: boolean | null
/** Time granularity forced onto every insight that supports one. Absent/null = inherit. */
interval?: IntervalTypeApi | null
metricFilters?: MetricsQueryFilterApi[] | null
/** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
metricVariables?: MetricsDashboardVariableApi[] | null
properties?:
| (
| EventPropertyFilterApi
| PersonPropertyFilterApi
| PersonMetadataPropertyFilterApi
| ElementPropertyFilterApi
| EventMetadataPropertyFilterApi
| SessionPropertyFilterApi
| CohortPropertyFilterApi
| RecordingPropertyFilterApi
| LogEntryPropertyFilterApi
| GroupPropertyFilterApi
| FeaturePropertyFilterApi
| FlagPropertyFilterApi
| HogQLPropertyFilterApi
| EmptyPropertyFilterApi
| DataWarehousePropertyFilterApi
| DataWarehousePersonPropertyFilterApi
| ErrorTrackingIssueFilterApi
| LogPropertyFilterApi
| MetricPropertyFilterApi
| SpanPropertyFilterApi
| RevenueAnalyticsPropertyFilterApi
| AccountCustomPropertyFilterApi
| WorkflowVariablePropertyFilterApi
| BehavioralPropertyFilterApi
)[]
| null
}
export type EndpointRefreshModeApi = (typeof EndpointRefreshModeApi)[keyof typeof EndpointRefreshModeApi]
export const EndpointRefreshModeApi = {
Cache: 'cache',
Force: 'force',
Direct: 'direct',
} as const
export interface EndpointRunRequestApi {
/** Client provided query ID. Can be used to retrieve the status or cancel the query. */
client_query_id?: string | null
/** Whether to include debug information (such as the executed HogQL) in the response. */
debug?: boolean | null
filters_override?: DashboardFilterApi | null
/** Maximum number of results to return. If not provided, returns all results. */
limit?: number | null
/** Number of results to skip. Must be used together with limit. Only supported for HogQL endpoints. */
offset?: number | null
refresh?: EndpointRefreshModeApi | null
/** Variables to parameterize the endpoint query. The key is the variable name and the value is the variable value.
*
* For HogQL endpoints: Keys must match a variable `code_name` defined in the query (referenced as `{variables.code_name}`). Example: `{"event_name": "$pageview"}`
*
* For non-materialized insight endpoints (e.g. TrendsQuery): - `date_from` and `date_to` are built-in variables that filter the date range. Example: `{"date_from": "2024-01-01", "date_to": "2024-01-31"}`
*
* For materialized insight endpoints: - Use the breakdown property name as the key to filter by breakdown value. Example: `{"$browser": "Chrome"}` - `date_from`/`date_to` are not supported on materialized insight endpoints.
*
* Unknown variable names will return a 400 error. */
variables?: EndpointRunRequestApiVariables
/** Specific endpoint version to execute. If not provided, the latest version is used. */
version?: number | null
}
export interface PaginatedEndpointVersionResponseListApi {
count: number
/** @nullable */
next?: string | null
/** @nullable */
previous?: string | null
results: EndpointVersionResponseApi[]
}
export interface EndpointLastExecutionTimesRequestApi {
names: string[]
}
export interface ClickhouseQueryProgressApi {
active_cpu_time: number
bytes_read: number
estimated_rows_total: number
rows_read: number
time_elapsed: number
}
export type QueryScanFixLocationApi = (typeof QueryScanFixLocationApi)[keyof typeof QueryScanFixLocationApi]
export const QueryScanFixLocationApi = {
Query: 'query',
Subquery: 'subquery',
View: 'view',
InsightDateRange: 'insight_date_range',
DashboardDateFilter: 'dashboard_date_filter',
} as const
export type QueryScanFindingKindApi = (typeof QueryScanFindingKindApi)[keyof typeof QueryScanFindingKindApi]
export const QueryScanFindingKindApi = {
NoEventFilter: 'no_event_filter',
NoStartDate: 'no_start_date',
PersonsJoin: 'persons_join',
} as const
export interface QueryScanWarningApi {
/** Whether the person can change the query so it reads less and still answers the same question. Surfaces show the full advice and "Fix with AI" only when a finding is actionable. */
actionable: boolean
/** True when the query reads this much on purpose, so reading less would change the answer. Absent means no. */
by_design?: boolean | null
/** A label for what in the query text kept the read wide, such as `in_or`. Only analytics and the assistant read it, and the labels can change. */
cause?: string | null
/** The one fact the finding rests on. */
evidence?: string | null
/** What "Fix with AI" and the assistant are told to do. */
fix: string
/** Where the change goes. Absent means the query itself. */
fix_location?: QueryScanFixLocationApi | null
kind: QueryScanFindingKindApi
/** Shown to the person: what happened and what to do. */
message: string
}
export interface QueryScanAnalysisApi {
/** The message the Fix with AI button sends to the assistant. Absent when no finding can be fixed in the query. */
assistant_prompt?: string | null
/** Every finding, fixable or not. Empty when the analysis found none. */
findings: QueryScanWarningApi[]
/** How much of all the project's events the query read, 0 to 1. */
project_share?: number | null
/** How much of the project's events in the query's date range the query read, 0 to 1. */
range_share?: number | null
}
export interface QueryScanSummaryApi {
/** The stored analysis, put on the response when it is served. Absent while the analysis runs, and when none was requested. */
analysis?: QueryScanAnalysisApi | null
/** True when the run asked for an analysis, or found one stored. While `analysis` is absent, poll `GET /query/scan/{cache_key}` for it. */
analysis_requested?: boolean | null
/** ClickHouse time for the last fresh run, summed over its ClickHouse queries. */
duration_ms: number
/** True when ClickHouse stopped the run instead of finishing it. */
killed?: boolean | null
/** Rows ClickHouse read for the last fresh run, all tables included. */
rows_read: number
}
export interface QueryStatusApi {
budget_remaining_bytes?: number | null
bytes_read?: number | null
/** Cache key of the run that failed, so clients can ask for its query scan. */
cache_key?: string | null
/** 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. */
complete?: boolean | null
dashboard_id?: number | null
/** When did the query execution task finish (whether successfully or not). */
end_time?: string | null
/** If the query failed, this will be set to true. More information can be found in the error_message field. */
error?: boolean | null
/** Stable machine-readable code for the error, when known: the DRF exception code, the ClickHouse error name, the HogQL error code, or `unhandled_<exception class>` for a failure that no handler classified. */
error_code?: string | null
error_message?: string | null
expiration_time?: string | null
id: string
insight_id?: number | null
labels?: string[] | null
/** When was the query execution task picked up by a worker. */
pickup_time?: string | null
/** ONLY async queries use QueryStatus. */
query_async?: true
query_progress?: ClickhouseQueryProgressApi | null
query_scan?: QueryScanSummaryApi | null
results?: unknown
/** When was query execution task enqueued. */
start_time?: string | null
task_id?: string | null
team_id: number
}
export interface QueryStatusResponseApi {
query_status: QueryStatusApi
}
export type EndpointsListParams = {
created_by?: number
is_active?: boolean
/**
* Number of results to return per page.
*/
limit?: number
/**
* The initial index from which to return the results.
*/
offset?: number
}
export type EndpointsRetrieveParams = {
/**
* Endpoint version to act on. Defaults to the current version.
*/
version?: number
}
export type EndpointsLogsRetrieveParams = {
/**
* Only return entries after this ISO 8601 timestamp. Defaults to 7 days ago; pass an explicit value to read further back.
*/
after?: string
/**
* Only return entries before this ISO 8601 timestamp.
*/
before?: string
/**
* Filter logs to a specific execution instance.
* @minLength 1
*/
instance_id?: string
/**
* Comma-separated log levels to include, e.g. 'WARN,ERROR'. Valid levels: DEBUG, LOG, INFO, WARN, ERROR.
* @minLength 1
*/
level?: string
/**
* Maximum number of log entries to return (1-500, default 50).
* @minimum 1
* @maximum 500
*/
limit?: number
/**
* Number of log entries to skip before the first returned entry (default 0).
* @minimum 0
*/
offset?: number
/**
* Case-insensitive substring search across log messages.
* @minLength 1
*/
search?: string
}
export type EndpointsMaterializationStatusRetrieveParams = {
/**
* Endpoint version to act on. Defaults to the current version.
*/
version?: number
}
export type EndpointsOpenapiSpecRetrieveParams = {
/**
* Endpoint version to act on. Defaults to the current version.
*/
version?: number
}
export type EndpointsVersionsListParams = {
created_by?: number
is_active?: boolean
/**
* Number of results to return per page.
*/
limit?: number
/**
* The initial index from which to return the results.
*/
offset?: number
}