Skip to content

: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.

42.4 KB
Raw Blame
/**
 * 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
}