> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpanel.com/llms.txt > Use this file to discover all available pages before exploring further. # List Workspace Data Definitions > List the data definitions of the workspace's project, ordered by name. > [!WARNING] > > **Closed Beta**\\ > > Available to a limited set of invited customers. Contact your account team to join. > The request and response contract may change before general availability (GA). ## OpenAPI ````yaml /openapi/platform.openapi.json get /v1/workspaces/{workspace_id}/data-definitions openapi: 3.1.0 info: title: Mixpanel Platform API version: '1' description: '' servers: - url: https://platform-us.mixpanel.com description: US - url: https://platform-eu.mixpanel.com description: EU - url: https://platform-in.mixpanel.com description: IN security: [] paths: /v1/workspaces/{workspace_id}/data-definitions: get: tags: - Workspaces - Data Definitions summary: List Workspace Data Definitions description: List the data definitions of the workspace's project, ordered by name. operationId: list_workspace_data_definitions parameters: - in: query name: page_size schema: default: 100 description: Items per page. maximum: 1000 minimum: 1 title: Page Size type: integer required: false description: Items per page. - in: query name: cursor schema: anyOf: - type: string - type: 'null' description: Previous or next cursor used to paginate. title: Cursor required: false description: Previous or next cursor used to paginate. - in: query name: order schema: default: asc description: 'Sort order by name: ''asc'' or ''desc''.' enum: - asc - desc title: Order type: string required: false description: 'Sort order by name: ''asc'' or ''desc''.' - in: query name: name schema: anyOf: - type: string - type: 'null' description: Case-insensitive substring of the definition name. title: Name required: false description: Case-insensitive substring of the definition name. - in: query name: type schema: description: Only definitions of these types. items: enum: - event - custom_event - event_property - custom_property - metric - behavior - cohort type: string title: Type type: array required: false description: Only definitions of these types. - in: query name: event_name schema: anyOf: - type: string - type: 'null' description: Only properties of this event. title: Event Name required: false description: Only properties of this event. - in: query name: status schema: description: Only definitions with one of these statuses. items: enum: - visible - hidden - blocked type: string title: Status type: array required: false description: Only definitions with one of these statuses. - in: query name: tag schema: description: Only definitions carrying one of these tags. items: type: string title: Tag type: array required: false description: Only definitions carrying one of these tags. - in: query name: owner_user_id schema: description: Only definitions owned by one of these users. items: maxLength: 64 minLength: 1 type: string title: Owner User Id type: array required: false description: Only definitions owned by one of these users. - in: query name: owner_team_id schema: description: Only definitions owned by one of these teams. items: maxLength: 64 minLength: 1 type: string title: Owner Team Id type: array required: false description: Only definitions owned by one of these teams. - in: query name: has_description schema: anyOf: - type: boolean - type: 'null' description: Whether the definition has a description. title: Has Description required: false description: Whether the definition has a description. - in: query name: has_owner schema: anyOf: - type: boolean - type: 'null' description: Whether the definition has an owner. title: Has Owner required: false description: Whether the definition has an owner. - in: query name: verified schema: anyOf: - type: boolean - type: 'null' description: Whether the definition is verified. title: Verified required: false description: Whether the definition is verified. - $ref: '#/components/parameters/WorkspaceIdPathParameter' - $ref: '#/components/parameters/MixpanelVersionHeader' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ListDataDefinitionsResponse' '422': $ref: '#/components/responses/RequestValidationError' default: $ref: '#/components/responses/Error' security: - ServiceAccountAuth: [] components: parameters: WorkspaceIdPathParameter: in: path name: workspace_id schema: title: Workspace ID type: string required: true description: The unique identifier for the workspace. MixpanelVersionHeader: in: header name: Mixpanel-Version required: false description: >- Optional date-based API version pin. If omitted, the request is served by the **latest** API version, and the caller accepts that a future release may introduce a breaking change to the response contract. If set to a supported version date, that version's contract is honored and will not receive a breaking change. schema: default: '2026-08-13' type: string title: Mixpanel-Version schemas: ListDataDefinitionsResponse: description: A page of a project's data definitions, ordered by name. properties: results: description: List of items for the current page. items: discriminator: mapping: behavior: '#/components/schemas/BehaviorDataDefinitionResponse' cohort: '#/components/schemas/CohortDataDefinitionResponse' custom_event: '#/components/schemas/CustomEventDataDefinitionResponse' custom_property: '#/components/schemas/CustomPropertyDataDefinitionResponse' event: '#/components/schemas/DataDefinitionWithoutBodyResponse' event_property: '#/components/schemas/DataDefinitionWithoutBodyResponse' metric: '#/components/schemas/MetricDataDefinitionResponse' propertyName: type oneOf: - $ref: '#/components/schemas/DataDefinitionWithoutBodyResponse' - $ref: '#/components/schemas/CustomEventDataDefinitionResponse' - $ref: '#/components/schemas/CustomPropertyDataDefinitionResponse' - $ref: '#/components/schemas/BehaviorDataDefinitionResponse' - $ref: '#/components/schemas/MetricDataDefinitionResponse' - $ref: '#/components/schemas/CohortDataDefinitionResponse' title: Results type: array pagination: $ref: '#/components/schemas/CursorPaginationResponse' description: Pagination cursors to navigate through the results. required: - results - pagination title: ListDataDefinitionsResponse type: object BehaviorDataDefinitionResponse: properties: id: description: Opaque definition ID, stable across renames. title: Id type: string name: description: The definition's name. title: Name type: string event_name: anyOf: - type: string - type: 'null' description: The parent event of an event property. title: Event Name display_name: anyOf: - type: string - type: 'null' description: The name shown in the UI. title: Display Name description: anyOf: - type: string - type: 'null' description: The definition's description. title: Description status: $ref: '#/components/schemas/EntityStatus' description: Whether the definition is visible, hidden, or blocked. verified: description: Whether the definition is verified. title: Verified type: boolean last_verified_at: anyOf: - format: date-time type: string - type: 'null' description: When the definition was last verified. title: Last Verified At last_verified_by: anyOf: - $ref: '#/components/schemas/DataDefinitionVerifier' - type: 'null' description: Who last verified the definition. tags: description: The definition's tag names. items: type: string title: Tags type: array owners: description: The definition's owners. items: $ref: '#/components/schemas/DataDefinitionOwner' title: Owners type: array merged_into: anyOf: - $ref: '#/components/schemas/DataDefinitionSummary' - type: 'null' description: The definition this one is merged into. first_tracked_at: anyOf: - format: date-time type: string - type: 'null' description: When data for the definition was first seen. title: First Tracked At created_at: description: When the definition was created. format: date-time title: Created At type: string updated_at: description: When the definition was last updated. format: date-time title: Updated At type: string type: const: behavior description: The kind of definition. title: Type type: string definition: anyOf: - description: >- Set `type` to `event` for events counted as they happen, `funnel` for ordered steps, or `retention` for a start event and a return event. discriminator: mapping: event: '#/components/schemas/EventBehavior' funnel: '#/components/schemas/FunnelBehavior' retention: '#/components/schemas/RetentionBehavior' propertyName: type oneOf: - $ref: '#/components/schemas/EventBehavior' - $ref: '#/components/schemas/FunnelBehavior' - $ref: '#/components/schemas/RetentionBehavior' - type: 'null' description: >- The behavior's query clause. Null when the stored definition cannot be expressed in this schema. Optional fields that are null or empty are left out of the definition. title: Definition required: - id - name - event_name - display_name - description - status - verified - last_verified_at - last_verified_by - tags - owners - merged_into - first_tracked_at - created_at - updated_at - type - definition title: BehaviorDataDefinitionResponse type: object CohortDataDefinitionResponse: properties: id: description: Opaque definition ID, stable across renames. title: Id type: string name: description: The definition's name. title: Name type: string event_name: anyOf: - type: string - type: 'null' description: The parent event of an event property. title: Event Name display_name: anyOf: - type: string - type: 'null' description: The name shown in the UI. title: Display Name description: anyOf: - type: string - type: 'null' description: The definition's description. title: Description status: $ref: '#/components/schemas/EntityStatus' description: Whether the definition is visible, hidden, or blocked. verified: description: Whether the definition is verified. title: Verified type: boolean last_verified_at: anyOf: - format: date-time type: string - type: 'null' description: When the definition was last verified. title: Last Verified At last_verified_by: anyOf: - $ref: '#/components/schemas/DataDefinitionVerifier' - type: 'null' description: Who last verified the definition. tags: description: The definition's tag names. items: type: string title: Tags type: array owners: description: The definition's owners. items: $ref: '#/components/schemas/DataDefinitionOwner' title: Owners type: array merged_into: anyOf: - $ref: '#/components/schemas/DataDefinitionSummary' - type: 'null' description: The definition this one is merged into. first_tracked_at: anyOf: - format: date-time type: string - type: 'null' description: When data for the definition was first seen. title: First Tracked At created_at: description: When the definition was created. format: date-time title: Created At type: string updated_at: description: When the definition was last updated. format: date-time title: Updated At type: string type: const: cohort description: The kind of definition. title: Type type: string definition: anyOf: - $ref: '#/components/schemas/CohortDefinition' - type: 'null' description: >- Who the cohort's members are. Null when the stored definition cannot be expressed in this schema. Optional fields that are null or empty are left out of the definition. required: - id - name - event_name - display_name - description - status - verified - last_verified_at - last_verified_by - tags - owners - merged_into - first_tracked_at - created_at - updated_at - type - definition title: CohortDataDefinitionResponse type: object CustomEventDataDefinitionResponse: properties: id: description: Opaque definition ID, stable across renames. title: Id type: string name: description: The definition's name. title: Name type: string event_name: anyOf: - type: string - type: 'null' description: The parent event of an event property. title: Event Name display_name: anyOf: - type: string - type: 'null' description: The name shown in the UI. title: Display Name description: anyOf: - type: string - type: 'null' description: The definition's description. title: Description status: $ref: '#/components/schemas/EntityStatus' description: Whether the definition is visible, hidden, or blocked. verified: description: Whether the definition is verified. title: Verified type: boolean last_verified_at: anyOf: - format: date-time type: string - type: 'null' description: When the definition was last verified. title: Last Verified At last_verified_by: anyOf: - $ref: '#/components/schemas/DataDefinitionVerifier' - type: 'null' description: Who last verified the definition. tags: description: The definition's tag names. items: type: string title: Tags type: array owners: description: The definition's owners. items: $ref: '#/components/schemas/DataDefinitionOwner' title: Owners type: array merged_into: anyOf: - $ref: '#/components/schemas/DataDefinitionSummary' - type: 'null' description: The definition this one is merged into. first_tracked_at: anyOf: - format: date-time type: string - type: 'null' description: When data for the definition was first seen. title: First Tracked At created_at: description: When the definition was created. format: date-time title: Created At type: string updated_at: description: When the definition was last updated. format: date-time title: Updated At type: string type: const: custom_event description: The kind of definition. title: Type type: string definition: anyOf: - $ref: '#/components/schemas/CustomEventDefinition' - type: 'null' description: >- The events the custom event combines. Null when the stored definition cannot be expressed in this schema. Optional fields that are null or empty are left out of the definition. required: - id - name - event_name - display_name - description - status - verified - last_verified_at - last_verified_by - tags - owners - merged_into - first_tracked_at - created_at - updated_at - type - definition title: CustomEventDataDefinitionResponse type: object CustomPropertyDataDefinitionResponse: properties: id: description: Opaque definition ID, stable across renames. title: Id type: string name: description: The definition's name. title: Name type: string event_name: anyOf: - type: string - type: 'null' description: The parent event of an event property. title: Event Name display_name: anyOf: - type: string - type: 'null' description: The name shown in the UI. title: Display Name description: anyOf: - type: string - type: 'null' description: The definition's description. title: Description status: $ref: '#/components/schemas/EntityStatus' description: Whether the definition is visible, hidden, or blocked. verified: description: Whether the definition is verified. title: Verified type: boolean last_verified_at: anyOf: - format: date-time type: string - type: 'null' description: When the definition was last verified. title: Last Verified At last_verified_by: anyOf: - $ref: '#/components/schemas/DataDefinitionVerifier' - type: 'null' description: Who last verified the definition. tags: description: The definition's tag names. items: type: string title: Tags type: array owners: description: The definition's owners. items: $ref: '#/components/schemas/DataDefinitionOwner' title: Owners type: array merged_into: anyOf: - $ref: '#/components/schemas/DataDefinitionSummary' - type: 'null' description: The definition this one is merged into. first_tracked_at: anyOf: - format: date-time type: string - type: 'null' description: When data for the definition was first seen. title: First Tracked At created_at: description: When the definition was created. format: date-time title: Created At type: string updated_at: description: When the definition was last updated. format: date-time title: Updated At type: string type: const: custom_property description: The kind of definition. title: Type type: string definition: anyOf: - $ref: '#/components/schemas/CustomPropertyDefinition' - type: 'null' description: >- How the custom property is computed. Null when the stored definition cannot be expressed in this schema. Optional fields that are null or empty are left out of the definition. required: - id - name - event_name - display_name - description - status - verified - last_verified_at - last_verified_by - tags - owners - merged_into - first_tracked_at - created_at - updated_at - type - definition title: CustomPropertyDataDefinitionResponse type: object DataDefinitionWithoutBodyResponse: description: An event or event property, which has no definition body. properties: id: description: Opaque definition ID, stable across renames. title: Id type: string name: description: The definition's name. title: Name type: string event_name: anyOf: - type: string - type: 'null' description: The parent event of an event property. title: Event Name display_name: anyOf: - type: string - type: 'null' description: The name shown in the UI. title: Display Name description: anyOf: - type: string - type: 'null' description: The definition's description. title: Description status: $ref: '#/components/schemas/EntityStatus' description: Whether the definition is visible, hidden, or blocked. verified: description: Whether the definition is verified. title: Verified type: boolean last_verified_at: anyOf: - format: date-time type: string - type: 'null' description: When the definition was last verified. title: Last Verified At last_verified_by: anyOf: - $ref: '#/components/schemas/DataDefinitionVerifier' - type: 'null' description: Who last verified the definition. tags: description: The definition's tag names. items: type: string title: Tags type: array owners: description: The definition's owners. items: $ref: '#/components/schemas/DataDefinitionOwner' title: Owners type: array merged_into: anyOf: - $ref: '#/components/schemas/DataDefinitionSummary' - type: 'null' description: The definition this one is merged into. first_tracked_at: anyOf: - format: date-time type: string - type: 'null' description: When data for the definition was first seen. title: First Tracked At created_at: description: When the definition was created. format: date-time title: Created At type: string updated_at: description: When the definition was last updated. format: date-time title: Updated At type: string type: description: The kind of definition. enum: - event - event_property title: Type type: string definition: description: Always null for this kind of definition. title: Definition type: 'null' required: - id - name - event_name - display_name - description - status - verified - last_verified_at - last_verified_by - tags - owners - merged_into - first_tracked_at - created_at - updated_at - type - definition title: DataDefinitionWithoutBodyResponse type: object MetricDataDefinitionResponse: properties: id: description: Opaque definition ID, stable across renames. title: Id type: string name: description: The definition's name. title: Name type: string event_name: anyOf: - type: string - type: 'null' description: The parent event of an event property. title: Event Name display_name: anyOf: - type: string - type: 'null' description: The name shown in the UI. title: Display Name description: anyOf: - type: string - type: 'null' description: The definition's description. title: Description status: $ref: '#/components/schemas/EntityStatus' description: Whether the definition is visible, hidden, or blocked. verified: description: Whether the definition is verified. title: Verified type: boolean last_verified_at: anyOf: - format: date-time type: string - type: 'null' description: When the definition was last verified. title: Last Verified At last_verified_by: anyOf: - $ref: '#/components/schemas/DataDefinitionVerifier' - type: 'null' description: Who last verified the definition. tags: description: The definition's tag names. items: type: string title: Tags type: array owners: description: The definition's owners. items: $ref: '#/components/schemas/DataDefinitionOwner' title: Owners type: array merged_into: anyOf: - $ref: '#/components/schemas/DataDefinitionSummary' - type: 'null' description: The definition this one is merged into. first_tracked_at: anyOf: - format: date-time type: string - type: 'null' description: When data for the definition was first seen. title: First Tracked At created_at: description: When the definition was created. format: date-time title: Created At type: string updated_at: description: When the definition was last updated. format: date-time title: Updated At type: string type: const: metric description: The kind of definition. title: Type type: string definition: anyOf: - description: >- One metric, or a formula's inputs followed by the formula, which refers to each input by its `display_name`. items: description: >- Set `type` to `event`, `funnel`, `retention`, `cohort`, or `formula` for a metric defined inline, or `saved_metric` for a saved metric. discriminator: mapping: cohort: '#/components/schemas/CohortMetric' event: '#/components/schemas/EventMetric' formula: '#/components/schemas/FormulaMetric' funnel: '#/components/schemas/FunnelMetric' retention: '#/components/schemas/RetentionMetric' saved_metric: '#/components/schemas/SavedMetric' propertyName: type oneOf: - $ref: '#/components/schemas/EventMetric' - $ref: '#/components/schemas/FunnelMetric' - $ref: '#/components/schemas/RetentionMetric' - $ref: '#/components/schemas/CohortMetric' - $ref: '#/components/schemas/FormulaMetric' - $ref: '#/components/schemas/SavedMetric' minItems: 1 type: array - type: 'null' description: >- The metric's query. Null when the stored definition cannot be expressed in this schema. Optional fields that are null or empty are left out of the definition. title: Definition required: - id - name - event_name - display_name - description - status - verified - last_verified_at - last_verified_by - tags - owners - merged_into - first_tracked_at - created_at - updated_at - type - definition title: MetricDataDefinitionResponse type: object CursorPaginationResponse: additionalProperties: false description: >- Response model for cursor-based pagination, containing the cursors for the next and previous pages. properties: previous_cursor: anyOf: - type: string - type: 'null' description: Cursor for the previous page. title: '' next_cursor: anyOf: - type: string - type: 'null' description: Cursor for the next page. title: '' title: CursorPaginationResponse type: object RequestValidationErrorResponse: properties: type: anyOf: - type: string - type: 'null' default: null description: A stable reference that identifies the problem type, if applicable. title: Type status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. title: Status type: integer instance: anyOf: - type: string - type: 'null' default: null description: >- A stable reference that identifies the specific occurrence of the problem, if applicable. title: Instance detail: anyOf: - type: string - type: 'null' default: null description: >- A human-readable explanation specific to this occurrence of the problem, if applicable. title: Detail error_id: anyOf: - type: string - type: 'null' default: null description: >- Opaque identifier for this error occurrence. Include it when contacting support so the corresponding server-side error can be located. title: Error Id errors: anyOf: - items: $ref: '#/components/schemas/RequestValidationErrorItem' type: array - type: 'null' default: null description: The set of request validation errors. title: Errors title: description: A short, human-readable summary of the problem type. readOnly: true title: Title type: string required: - status - title title: RequestValidationErrorResponse type: object ErrorResponse: properties: type: anyOf: - type: string - type: 'null' default: null description: A stable reference that identifies the problem type, if applicable. title: Type status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. title: Status type: integer instance: anyOf: - type: string - type: 'null' default: null description: >- A stable reference that identifies the specific occurrence of the problem, if applicable. title: Instance detail: anyOf: - type: string - type: 'null' default: null description: >- A human-readable explanation specific to this occurrence of the problem, if applicable. title: Detail error_id: anyOf: - type: string - type: 'null' default: null description: >- Opaque identifier for this error occurrence. Include it when contacting support so the corresponding server-side error can be located. title: Error Id title: description: A short, human-readable summary of the problem type. readOnly: true title: Title type: string required: - status - title title: ErrorResponse type: object EntityStatus: enum: - visible - hidden - blocked title: EntityStatus type: string DataDefinitionVerifier: properties: type: $ref: '#/components/schemas/OwnerType' description: Whether the verifier is a user or a team. id: description: The verifier's user or team ID. title: Id type: string display_name: anyOf: - type: string - type: 'null' description: The verifier's name. title: Display Name required: - type - id - display_name title: DataDefinitionVerifier type: object DataDefinitionOwner: properties: type: $ref: '#/components/schemas/OwnerType' description: Whether the owner is a user or a team. id: description: The owner's user or team ID. title: Id type: string display_name: anyOf: - type: string - type: 'null' description: The owner's name. title: Display Name resolved: description: Whether the owner still exists. title: Resolved type: boolean required: - type - id - display_name - resolved title: DataDefinitionOwner type: object DataDefinitionSummary: properties: id: description: The definition's ID. title: Id type: string name: description: The definition's name. title: Name type: string required: - id - name title: DataDefinitionSummary type: object EventBehavior: additionalProperties: false properties: type: const: event description: >- Set `type` to `event` for events counted as they happen, `funnel` for ordered steps, or `retention` for a start event and a return event. title: Type type: string events: items: description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' minItems: 1 title: Events type: array required: - type - events title: EventBehavior type: object FunnelBehavior: additionalProperties: false properties: type: const: funnel description: >- Set `type` to `event` for events counted as they happen, `funnel` for ordered steps, or `retention` for a start event and a return event. title: Type type: string steps: description: The funnel steps, first to last. items: $ref: '#/components/schemas/FunnelStep' maxItems: 25 minItems: 2 title: Steps type: array conversion_window: allOf: - $ref: '#/components/schemas/ConversionWindow' default: value: 7 unit: day description: >- How long after the first step the funnel must complete: a span of time or up to 12 sessions. Defaults to 7 days. order: allOf: - $ref: '#/components/schemas/FunnelOrder' default: ordered description: >- ordered: steps in sequence, other events may occur between them. any: the steps after the first may happen in any order. hold_constant: default: [] description: Properties whose value must stay the same across a user's steps. items: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Hold Constant type: array exclusions: default: [] items: $ref: '#/components/schemas/FunnelExclusion' title: Exclusions type: array reentry_mode: default: basic description: >- How a user who starts the funnel again before finishing it is counted. enum: - basic - optimized title: Reentry Mode type: string required: - type - steps title: FunnelBehavior type: object RetentionBehavior: additionalProperties: false properties: type: const: retention description: >- Set `type` to `event` for events counted as they happen, `funnel` for ordered steps, or `retention` for a start event and a return event. title: Type type: string start_event: description: The event that starts an entity's retention clock. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Start Event return_event: description: The event that counts as returning. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Return Event unit: allOf: - $ref: '#/components/schemas/RetentionUnit' default: day description: The size of each retention bucket after the start event. criteria: allOf: - $ref: '#/components/schemas/RetentionCriteria' default: 'on' description: >- When a return event counts toward a bucket: on that bucket only, on it or any later one, on it or any earlier one, or on every bucket up to it (streak). alignment: default: birth description: >- `birth` measures buckets from each user's start event, `interval_start` from the start of the interval the start event happened in. enum: - birth - interval_start title: Alignment type: string custom_bucket_sizes: default: [] description: Bucket widths in `unit`s, when the buckets are not one unit each. items: type: integer title: Custom Bucket Sizes type: array required: - type - start_event - return_event title: RetentionBehavior type: object CohortDefinition: additionalProperties: false properties: groups: items: $ref: '#/components/schemas/CohortGroup' minItems: 1 title: Groups type: array groups_logical_operator: allOf: - $ref: '#/components/schemas/LogicalOperators' default: AND required: - groups title: CohortDefinition type: object CustomEventDefinition: additionalProperties: false properties: events: description: An event matching any of these counts as the custom event. items: description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Events type: array required: - events title: CustomEventDefinition type: object CustomPropertyDefinition: additionalProperties: false description: >- ``formula`` refers to ``properties`` by key. ``is_session_scoped`` computes the value per session. properties: source: enum: - event - profile title: Source type: string formula: title: Formula type: string properties: type: object additionalProperties: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/CustomPropertyEventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/CustomPropertyEventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' default: {} title: Properties is_session_scoped: default: false title: Is Session Scoped type: boolean required: - source - formula title: CustomPropertyDefinition type: object CohortMetric: additionalProperties: false properties: display_name: anyOf: - maxLength: 128 type: string - type: 'null' title: Display Name group_key: default: User description: >- The raw group key name, as shown in Project Settings—for example `$company_id`. `User` is the user profile and the default. minLength: 1 title: Group Key type: string measurement: allOf: - $ref: '#/components/schemas/CohortCountMeasurement' default: type: count interval_aggregation: standard type: const: cohort title: Type type: string cohort_id: description: Id of the saved cohort. minLength: 1 title: Cohort Id type: string filters: default: [] description: Profile property or cohort filters narrowing the members counted. items: description: >- Set `type` to `property` to filter on a property value, or `cohort` to filter on cohort membership. discriminator: mapping: cohort: '#/components/schemas/CohortFilter' property: '#/components/schemas/PropertyFilter' propertyName: type oneOf: - $ref: '#/components/schemas/PropertyFilter' - $ref: '#/components/schemas/CohortFilter' title: Filters type: array required: - type - cohort_id title: CohortMetric type: object EventMetric: additionalProperties: false properties: display_name: anyOf: - maxLength: 128 type: string - type: 'null' title: Display Name group_key: default: User description: >- The raw group key name, as shown in Project Settings—for example `$company_id`. `User` is the user profile and the default. minLength: 1 title: Group Key type: string measurement: description: >- What the metric calculates. Set `type` to `count`, `property`, `frequency_per_user`, or `property_per_user`. discriminator: mapping: count: '#/components/schemas/EventCountMeasurement' frequency_per_user: '#/components/schemas/EventFrequencyPerUserMeasurement' property: '#/components/schemas/EventPropertyMeasurement' property_per_user: '#/components/schemas/EventPropertyPerUserMeasurement' propertyName: type oneOf: - $ref: '#/components/schemas/EventCountMeasurement' - $ref: '#/components/schemas/EventPropertyMeasurement' - $ref: '#/components/schemas/EventFrequencyPerUserMeasurement' - $ref: '#/components/schemas/EventPropertyPerUserMeasurement' title: Measurement type: const: event title: Type type: string events: items: description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' minItems: 1 title: Events type: array required: - measurement - type - events title: EventMetric type: object FormulaMetric: additionalProperties: false properties: type: const: formula title: Type type: string display_name: anyOf: - maxLength: 128 type: string - type: 'null' title: Display Name formula: description: >- Arithmetic over other metrics in this request, each named by its `display_name` in curly braces: `{Purchases} / {Signups} * 100`. Supports `+ - * / ^`, parentheses, and numbers. Formulas cannot reference other formulas. minLength: 1 title: Formula type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation required: - type - formula title: FormulaMetric type: object FunnelMetric: additionalProperties: false properties: display_name: anyOf: - maxLength: 128 type: string - type: 'null' title: Display Name group_key: default: User description: >- The raw group key name, as shown in Project Settings—for example `$company_id`. `User` is the user profile and the default. minLength: 1 title: Group Key type: string measurement: description: >- What the metric calculates. Set `type` to `conversion_rate`, `count`, `time_to_convert`, or `property`. discriminator: mapping: conversion_rate: '#/components/schemas/FunnelConversionRateMeasurement' count: '#/components/schemas/FunnelCountMeasurement' property: '#/components/schemas/FunnelPropertyMeasurement' time_to_convert: '#/components/schemas/FunnelTimeToConvertMeasurement' propertyName: type oneOf: - $ref: '#/components/schemas/FunnelConversionRateMeasurement' - $ref: '#/components/schemas/FunnelCountMeasurement' - $ref: '#/components/schemas/FunnelTimeToConvertMeasurement' - $ref: '#/components/schemas/FunnelPropertyMeasurement' title: Measurement type: const: funnel title: Type type: string steps: description: The funnel steps, first to last. items: $ref: '#/components/schemas/FunnelStep' maxItems: 25 minItems: 2 title: Steps type: array conversion_window: allOf: - $ref: '#/components/schemas/ConversionWindow' default: value: 7 unit: day description: >- How long after the first step the funnel must complete: a span of time or up to 12 sessions. Defaults to 7 days. Measurements with the `total_sessions` calculation accept only one session. order: allOf: - $ref: '#/components/schemas/FunnelOrder' default: ordered description: >- ordered: steps in sequence, other events may occur between them. any: the steps after the first may happen in any order. hold_constant: default: [] description: Properties whose value must stay the same across a user's steps. items: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Hold Constant type: array exclusions: default: [] items: $ref: '#/components/schemas/FunnelExclusion' title: Exclusions type: array reentry_mode: default: basic description: >- How a user who starts the funnel again before finishing it is counted. enum: - basic - optimized title: Reentry Mode type: string required: - measurement - type - steps title: FunnelMetric type: object RetentionMetric: additionalProperties: false properties: display_name: anyOf: - maxLength: 128 type: string - type: 'null' title: Display Name group_key: default: User description: >- The raw group key name, as shown in Project Settings—for example `$company_id`. `User` is the user profile and the default. minLength: 1 title: Group Key type: string measurement: description: >- What the metric reports. Set `type` to `retention_rate`, `count`, or `property`. discriminator: mapping: count: '#/components/schemas/RetentionCountMeasurement' property: '#/components/schemas/RetentionPropertyMeasurement' retention_rate: '#/components/schemas/RetentionRateMeasurement' propertyName: type oneOf: - $ref: '#/components/schemas/RetentionRateMeasurement' - $ref: '#/components/schemas/RetentionCountMeasurement' - $ref: '#/components/schemas/RetentionPropertyMeasurement' title: Measurement type: const: retention title: Type type: string start_event: description: The event that starts an entity's retention clock. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Start Event return_event: description: The event that counts as returning. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Return Event unit: allOf: - $ref: '#/components/schemas/RetentionUnit' default: day description: The size of each retention bucket after the start event. bucket: default: 0 description: >- Which retention bucket to report, in `unit`s after the start event: 0 is the start bucket; with unit `day`, 7 is Day 7. Must be within the project's retention interval limit, 60 by default. minimum: 0 title: Bucket type: integer criteria: allOf: - $ref: '#/components/schemas/RetentionCriteria' default: 'on' description: >- When a return event counts toward the bucket: on that bucket only, on it or any later one, on it or any earlier one, or on every bucket up to it (streak). alignment: default: birth description: >- `birth` measures buckets from each user's start event, `interval_start` from the start of the interval the start event happened in. enum: - birth - interval_start title: Alignment type: string custom_bucket_sizes: default: [] description: Bucket widths in `unit`s, when the buckets are not one unit each. items: type: integer title: Custom Bucket Sizes type: array required: - measurement - type - start_event - return_event title: RetentionMetric type: object SavedMetric: additionalProperties: false description: A saved metric, as an input to a formula. properties: type: const: saved_metric title: Type type: string metric_id: description: Id of the saved metric. minLength: 1 title: Metric Id type: string display_name: anyOf: - maxLength: 128 type: string - type: 'null' title: Display Name required: - type - metric_id title: SavedMetric type: object RequestValidationErrorItem: properties: type: description: Machine-readable validation error type, e.g. 'missing'. title: Type type: string loc: description: Location of the offending value in the request. items: anyOf: - type: string - type: integer title: Loc type: array msg: description: Human-readable description of the error. title: Msg type: string ctx: anyOf: - additionalProperties: true type: object - type: 'null' default: null description: Additional context about the error, if any. title: Ctx required: - type - loc - msg title: RequestValidationErrorItem type: object OwnerType: enum: - user - team title: OwnerType type: string CustomEvent: additionalProperties: false properties: filters: default: [] items: description: >- Set `type` to `property` to filter on a property value, or `cohort` to filter on cohort membership. Set `type` to `first_time` to keep only the first time each user did the event. discriminator: mapping: cohort: '#/components/schemas/CohortFilter' first_time: '#/components/schemas/FirstTimeFilter' property: '#/components/schemas/PropertyFilter' propertyName: type oneOf: - $ref: '#/components/schemas/PropertyFilter' - $ref: '#/components/schemas/CohortFilter' - $ref: '#/components/schemas/FirstTimeFilter' title: Filters type: array filters_logical_operator: allOf: - $ref: '#/components/schemas/LogicalOperators' default: AND event_type: const: custom_event description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. title: Event Type type: string id: description: Id of the custom event. minLength: 1 title: Id type: string required: - event_type - id title: CustomEvent type: object Event: additionalProperties: false properties: filters: default: [] items: description: >- Set `type` to `property` to filter on a property value, or `cohort` to filter on cohort membership. Set `type` to `first_time` to keep only the first time each user did the event. discriminator: mapping: cohort: '#/components/schemas/CohortFilter' first_time: '#/components/schemas/FirstTimeFilter' property: '#/components/schemas/PropertyFilter' propertyName: type oneOf: - $ref: '#/components/schemas/PropertyFilter' - $ref: '#/components/schemas/CohortFilter' - $ref: '#/components/schemas/FirstTimeFilter' title: Filters type: array filters_logical_operator: allOf: - $ref: '#/components/schemas/LogicalOperators' default: AND name: description: Name of the event as tracked, not its Lexicon display name. title: Name type: string event_type: const: event description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. title: Event Type type: string required: - name - event_type title: Event type: object FunnelStep: additionalProperties: false properties: event: description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Event alternative_events: default: [] description: Other events that also complete the step. items: description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Alternative Events type: array order: anyOf: - $ref: '#/components/schemas/FunnelOrder' - type: 'null' description: >- The step's order when it differs from the funnel's: `any` lets the step happen in any order relative to the other `any` steps. required: - event title: FunnelStep type: object ConversionWindow: additionalProperties: false description: How long after the first step an entity has to complete the funnel. properties: value: description: >- Whole number of `unit`s, at most 31708800 seconds, 528480 minutes, 8808 hours, 367 days, 52 weeks, 12 months, 12 sessions. exclusiveMinimum: 0 title: Value type: integer unit: $ref: '#/components/schemas/ConversionWindowUnit' description: >- `session` counts sessions instead of time: with value N, the funnel must complete within the session of the first step or the N - 1 sessions after it. required: - value - unit title: ConversionWindow type: object FunnelOrder: description: |- `ordered`: steps in sequence, other events may occur between them. `any`: the steps after the first may happen in any order. enum: - ordered - any title: FunnelOrder type: string EventProperty: additionalProperties: false description: A property recorded on the event. properties: type: $ref: '#/components/schemas/PropertyType' path: anyOf: - items: minLength: 1 type: string minItems: 1 type: array - type: 'null' description: Key path into an object-valued property. title: Path list_item: anyOf: - $ref: '#/components/schemas/ListItem' - type: 'null' description: Required for, and only for, `list[object]`. source: const: event description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. title: Source type: string name: minLength: 1 title: Name type: string required: - type - source - name title: EventProperty type: object EventCustomProperty: additionalProperties: false description: A saved custom property computed on the event, by id. properties: type: $ref: '#/components/schemas/PropertyType' path: anyOf: - items: minLength: 1 type: string minItems: 1 type: array - type: 'null' description: Key path into an object-valued property. title: Path list_item: anyOf: - $ref: '#/components/schemas/ListItem' - type: 'null' description: Required for, and only for, `list[object]`. source: const: event_custom description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. title: Source type: string id: minLength: 1 title: Id type: string required: - type - source - id title: EventCustomProperty type: object LookupProperty: additionalProperties: false description: >- A column of a lookup table, reached through the property it is joined on. The table is not named: each join key maps to at most one lookup table, and a column name alone is ambiguous across tables. Group profiles are not lookup tables; their properties are `profile` properties with a `group_key`. properties: type: $ref: '#/components/schemas/PropertyType' path: anyOf: - items: minLength: 1 type: string minItems: 1 type: array - type: 'null' description: Key path into an object-valued property. title: Path list_item: anyOf: - $ref: '#/components/schemas/ListItem' - type: 'null' description: Required for, and only for, `list[object]`. source: const: lookup description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. title: Source type: string join_key: description: >- The property the lookup table is joined on. Set `source` to `event`, `profile`, `event_custom`, or `profile_custom`. discriminator: mapping: event: '#/components/schemas/EventJoinKey' event_custom: '#/components/schemas/EventCustomJoinKey' profile: '#/components/schemas/ProfileJoinKey' profile_custom: '#/components/schemas/ProfileCustomJoinKey' propertyName: source oneOf: - $ref: '#/components/schemas/EventJoinKey' - $ref: '#/components/schemas/ProfileJoinKey' - $ref: '#/components/schemas/EventCustomJoinKey' - $ref: '#/components/schemas/ProfileCustomJoinKey' title: Join Key column: description: >- Name of the column to read from the lookup table joined on `join_key`. minLength: 1 title: Column type: string required: - type - source - join_key - column title: LookupProperty type: object ProfileProperty: additionalProperties: false description: |- A property on a user profile or a group profile (company, organization, ...), read as of query time. `group_key` names which profile. properties: type: $ref: '#/components/schemas/PropertyType' path: anyOf: - items: minLength: 1 type: string minItems: 1 type: array - type: 'null' description: Key path into an object-valued property. title: Path list_item: anyOf: - $ref: '#/components/schemas/ListItem' - type: 'null' description: Required for, and only for, `list[object]`. source: const: profile description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. title: Source type: string name: minLength: 1 title: Name type: string group_key: default: User description: >- The raw group key name, as shown in Project Settings—for example `$company_id`. `User` is the user profile and the default. minLength: 1 title: Group Key type: string required: - type - source - name title: ProfileProperty type: object ProfileCustomProperty: additionalProperties: false description: |- A saved custom property computed on a user or group profile, by id. `group_key` names which profile, as for `profile` properties. properties: type: $ref: '#/components/schemas/PropertyType' path: anyOf: - items: minLength: 1 type: string minItems: 1 type: array - type: 'null' description: Key path into an object-valued property. title: Path list_item: anyOf: - $ref: '#/components/schemas/ListItem' - type: 'null' description: Required for, and only for, `list[object]`. source: const: profile_custom description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. title: Source type: string id: minLength: 1 title: Id type: string group_key: default: User description: >- The raw group key name, as shown in Project Settings—for example `$company_id`. `User` is the user profile and the default. minLength: 1 title: Group Key type: string required: - type - source - id title: ProfileCustomProperty type: object FunnelExclusion: additionalProperties: false description: >- An event that drops a user from the funnel when it happens between two steps. properties: event: description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Event from_step: description: The 1-based step the exclusion starts after. minimum: 1 title: From Step type: integer to_step: description: The 1-based step the exclusion ends before. minimum: 2 title: To Step type: integer required: - event - from_step - to_step title: FunnelExclusion type: object RetentionUnit: enum: - day - week - month title: RetentionUnit type: string RetentionCriteria: description: >- When a return event counts toward a bucket: `on` that bucket only, `on_or_after` that bucket or any later one, `on_or_before` that bucket or any earlier one, `streak` every bucket up to and including it. enum: - 'on' - on_or_after - on_or_before - streak title: RetentionCriteria type: string CohortGroup: additionalProperties: false description: Users who match the group's filters and its behaviors. properties: cohort_id: anyOf: - minLength: 1 type: string - type: 'null' description: Only members of this cohort. Null means all users. title: Cohort Id filters: default: [] description: Profile property and cohort membership filters. items: description: >- Set `type` to `property` to filter on a property value, or `cohort` to filter on cohort membership. Set `type` to `first_time` to keep only the first time each user did the event. discriminator: mapping: cohort: '#/components/schemas/CohortFilter' first_time: '#/components/schemas/FirstTimeFilter' property: '#/components/schemas/PropertyFilter' propertyName: type oneOf: - $ref: '#/components/schemas/PropertyFilter' - $ref: '#/components/schemas/CohortFilter' - $ref: '#/components/schemas/FirstTimeFilter' title: Filters type: array filters_logical_operator: allOf: - $ref: '#/components/schemas/LogicalOperators' default: AND behaviors: default: [] items: $ref: '#/components/schemas/BehaviorCriterion' title: Behaviors type: array behaviors_logical_operator: allOf: - $ref: '#/components/schemas/LogicalOperators' default: AND title: CohortGroup type: object LogicalOperators: description: >- How a list of filters is combined: `AND` keeps what matches every filter, `OR` what matches any of them. enum: - AND - OR title: LogicalOperators type: string CustomPropertyEventProperty: additionalProperties: false properties: type: $ref: '#/components/schemas/PropertyType' path: anyOf: - items: minLength: 1 type: string minItems: 1 type: array - type: 'null' description: Key path into an object-valued property. title: Path list_item: anyOf: - $ref: '#/components/schemas/ListItem' - type: 'null' description: Required for, and only for, `list[object]`. source: const: event description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. title: Source type: string name: minLength: 1 title: Name type: string from_event: anyOf: - description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' - type: 'null' description: >- The event the value is read from, when it is not the event being read. title: From Event required: - type - source - name title: CustomPropertyEventProperty type: object CohortCountMeasurement: additionalProperties: false properties: type: const: count default: count title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation title: CohortCountMeasurement type: object CohortFilter: additionalProperties: false description: Keeps users who are, or are not, members of a saved cohort. properties: type: const: cohort title: Type type: string cohort_id: minLength: 1 title: Cohort Id type: string operator: allOf: - $ref: '#/components/schemas/CohortOperator' default: in required: - type - cohort_id title: CohortFilter type: object PropertyFilter: additionalProperties: false description: Filters events or profiles by a property value. properties: type: const: property title: Type type: string property: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Property operator: $ref: '#/components/schemas/Operator' values: anyOf: - items: anyOf: - type: string - type: integer - type: number - type: boolean type: array - type: 'null' description: >- Operands. Omitted for `is set`, `is not set`, `is true`, `is false`; exactly two for `is between` / `is not between`; one for `contains`, `does not contain` and the other number operators; one or more for `equals` / `does not equal`, any of which may match. title: Values list_match: anyOf: - $ref: '#/components/schemas/ListMatch' - type: 'null' description: >- For list-valued properties, and for lookup columns whose join key is list-valued. Defaults to `any`. list_item_match: anyOf: - $ref: '#/components/schemas/ListMatch' - type: 'null' description: >- For `list[object]` properties whose `list_item` is list-valued: whether any or all elements of each object's list must pass. Defaults to `any`. `list_match` quantifies over the objects. keep_only_matching: default: false description: >- For list-valued properties with `list_match: any`: drop the list elements that did not match instead of keeping the whole list. title: Keep Only Matching type: boolean required: - type - property - operator title: PropertyFilter type: object EventCountMeasurement: additionalProperties: false description: Counts matching events, sessions, or users. properties: type: const: count description: >- What the metric calculates. Set `type` to `count`, `property`, `frequency_per_user`, or `property_per_user`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: $ref: '#/components/schemas/CalculationType' required: - type - calculation title: EventCountMeasurement type: object EventFrequencyPerUserMeasurement: additionalProperties: false description: A statistic over how many matching events each user performed. properties: type: const: frequency_per_user description: >- What the metric calculates. Set `type` to `count`, `property`, `frequency_per_user`, or `property_per_user`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: enum: - distribution - average - percentile - min - max title: Calculation type: string percentile: anyOf: - exclusiveMaximum: 100 exclusiveMinimum: 0 type: number - type: 'null' description: >- The percentile to compute, strictly between 0 and 100; 50 is the median. Required for, and only for, calculation `percentile`. title: Percentile required: - type - calculation title: EventFrequencyPerUserMeasurement type: object EventPropertyMeasurement: additionalProperties: false description: |- A statistic over a property's values across all matching events. Every calculation except `distinct_count` needs a number property. properties: type: const: property description: >- What the metric calculates. Set `type` to `count`, `property`, `frequency_per_user`, or `property_per_user`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: enum: - sum - average - percentile - min - max - distinct_count title: Calculation type: string percentile: anyOf: - exclusiveMaximum: 100 exclusiveMinimum: 0 type: number - type: 'null' description: >- The percentile to compute, strictly between 0 and 100; 50 is the median. Required for, and only for, calculation `percentile`. title: Percentile property: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Property required: - type - calculation - property title: EventPropertyMeasurement type: object EventPropertyPerUserMeasurement: additionalProperties: false description: |- Aggregates a property for each user, then a statistic across users. `per_user` other than `distinct_count` needs a number property. properties: type: const: property_per_user description: >- What the metric calculates. Set `type` to `count`, `property`, `frequency_per_user`, or `property_per_user`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: enum: - distribution - sum - average - percentile - min - max title: Calculation type: string percentile: anyOf: - exclusiveMaximum: 100 exclusiveMinimum: 0 type: number - type: 'null' description: >- The percentile to compute, strictly between 0 and 100; 50 is the median. Required for, and only for, calculation `percentile`. title: Percentile property: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Property per_user: description: >- What is computed for each user (each `group_key` entity) before `calculation` runs across users. enum: - sum - average - distinct_count - min - max title: Per User type: string required: - type - calculation - property - per_user title: EventPropertyPerUserMeasurement type: object RollingAverage: additionalProperties: false description: |- A rolling average over a number of time buckets. The request must set `time.unit`, which sizes each bucket. properties: size: description: Number of time buckets to average over. title: Size type: integer required: - size title: RollingAverage type: object FunnelConversionRateMeasurement: additionalProperties: false description: >- The share of entities that complete the funnel, counted per `calculation`. properties: type: const: conversion_rate description: >- What the metric calculates. Set `type` to `conversion_rate`, `count`, `time_to_convert`, or `property`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: default: unique_users description: >- Determines how conversions are counted: total users, events, or sessions. With `total_sessions`, the metric's `conversion_window` defaults to one session and accepts no other value. enum: - unique_users - total_events - total_sessions title: Calculation type: string required: - type title: FunnelConversionRateMeasurement type: object FunnelCountMeasurement: additionalProperties: false description: Counts the entities, events, or sessions that complete the funnel. properties: type: const: count description: >- What the metric calculates. Set `type` to `conversion_rate`, `count`, `time_to_convert`, or `property`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: description: >- Determines how conversions are counted: total users, events, or sessions. With `total_sessions`, the metric's `conversion_window` defaults to one session and accepts no other value. enum: - unique_users - total_events - total_sessions title: Calculation type: string required: - type - calculation title: FunnelCountMeasurement type: object FunnelPropertyMeasurement: additionalProperties: false description: >- The sum of a number property over the last-step event of each conversion. properties: type: const: property description: >- What the metric calculates. Set `type` to `conversion_rate`, `count`, `time_to_convert`, or `property`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: const: sum default: sum title: Calculation type: string property: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Property required: - type - property title: FunnelPropertyMeasurement type: object FunnelTimeToConvertMeasurement: additionalProperties: false description: A statistic over how long converting entities took, in seconds. properties: type: const: time_to_convert description: >- What the metric calculates. Set `type` to `conversion_rate`, `count`, `time_to_convert`, or `property`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: enum: - average - percentile - min - max title: Calculation type: string percentile: anyOf: - exclusiveMaximum: 100 exclusiveMinimum: 0 type: number - type: 'null' description: >- The percentile to compute, strictly between 0 and 100; 50 is the median. Required for, and only for, calculation `percentile`. title: Percentile required: - type - calculation title: FunnelTimeToConvertMeasurement type: object RetentionCountMeasurement: additionalProperties: false description: Counts the entities retained in the bucket. properties: type: const: count description: >- What the metric reports. Set `type` to `retention_rate`, `count`, or `property`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: const: unique_users default: unique_users title: Calculation type: string required: - type title: RetentionCountMeasurement type: object RetentionPropertyMeasurement: additionalProperties: false description: >- A number property over the cohort's return events in the bucket: `sum` adds it up, `average` is the mean of each cohort member's sum, counting members who did not return as 0. properties: type: const: property description: >- What the metric reports. Set `type` to `retention_rate`, `count`, or `property`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation calculation: enum: - sum - average title: Calculation type: string property: description: >- Set `source` to `event` for a property recorded on the event, `profile` for a property on a user profile or a data group profile named by `group_key`, `event_custom` or `profile_custom` for a saved custom property computed on events or profiles, or `lookup` for a column of a lookup table. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Property required: - type - calculation - property title: RetentionPropertyMeasurement type: object RetentionRateMeasurement: additionalProperties: false description: >- The share of entities that did the start event and returned in the bucket. properties: type: const: retention_rate description: >- What the metric reports. Set `type` to `retention_rate`, `count`, or `property`. title: Type type: string interval_aggregation: anyOf: - enum: - standard - cumulative type: string - $ref: '#/components/schemas/RollingAverage' default: standard title: Interval Aggregation required: - type title: RetentionRateMeasurement type: object FirstTimeFilter: additionalProperties: false description: Keeps only the first time each user did the event. properties: type: const: first_time title: Type type: string required: - type title: FirstTimeFilter type: object ConversionWindowUnit: enum: - second - minute - hour - day - week - month - session title: ConversionWindowUnit type: string PropertyType: description: |- The type a property's value is interpreted as. Required, because the query does not look a property's type up. `list[object]` is only usable together with `list_item`, which picks one key out of each object. enum: - string - number - boolean - datetime - list[string] - list[number] - list[boolean] - list[datetime] - list[list] - list[object] title: PropertyType type: string ListItem: additionalProperties: false description: >- Reads one primitive key out of each object in a `list[object]` property, so the list can be filtered or broken down like a `list[]`. `key_path` is the path from the object root to the leaf value: `["sku"]` for a top-level key, `["details", "sku"]` for a nested one. properties: key_path: items: minLength: 1 type: string minItems: 1 title: Key Path type: array type: enum: - string - number - boolean - datetime - list[string] - list[number] - list[boolean] - list[datetime] - list[list] title: Type type: string required: - key_path - type title: ListItem type: object EventJoinKey: additionalProperties: false description: An event property a lookup table is attached to. properties: source: const: event description: >- The property the lookup table is joined on. Set `source` to `event`, `profile`, `event_custom`, or `profile_custom`. title: Source type: string name: description: Name of the event property. minLength: 1 title: Name type: string required: - source - name title: EventJoinKey type: object EventCustomJoinKey: additionalProperties: false description: A saved event custom property a lookup table is attached to. properties: source: const: event_custom description: >- The property the lookup table is joined on. Set `source` to `event`, `profile`, `event_custom`, or `profile_custom`. title: Source type: string id: minLength: 1 title: Id type: string required: - source - id title: EventCustomJoinKey type: object ProfileJoinKey: additionalProperties: false description: |- A user profile property a lookup table is attached to. A `profile` join key always means the `$user_id` profile. properties: source: const: profile description: >- The property the lookup table is joined on. Set `source` to `event`, `profile`, `event_custom`, or `profile_custom`. title: Source type: string name: description: Name of the user profile property. minLength: 1 title: Name type: string required: - source - name title: ProfileJoinKey type: object ProfileCustomJoinKey: additionalProperties: false description: |- A saved user profile custom property a lookup table is attached to. A `profile_custom` join key always means the `$user_id` profile. properties: source: const: profile_custom description: >- The property the lookup table is joined on. Set `source` to `event`, `profile`, `event_custom`, or `profile_custom`. title: Source type: string id: minLength: 1 title: Id type: string required: - source - id title: ProfileCustomJoinKey type: object BehaviorCriterion: additionalProperties: false description: >- A user matches when their measurement of the event over the date range compares as ``operator`` to ``values``. A count that `is equal to` 0 matches users who did not do the event. properties: event: description: >- Set `event_type` to `event` for an event tracked into the project, or `custom_event` for a saved custom event. discriminator: mapping: custom_event: '#/components/schemas/CustomEvent' event: '#/components/schemas/Event' propertyName: event_type oneOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/CustomEvent' title: Event measurement: description: >- `count` counts each user's events. `property` takes a statistic of an event property over each user's events. discriminator: mapping: count: '#/components/schemas/BehaviorEventCount' property: '#/components/schemas/BehaviorPropertyStatistic' propertyName: type oneOf: - $ref: '#/components/schemas/BehaviorEventCount' - $ref: '#/components/schemas/BehaviorPropertyStatistic' title: Measurement operator: $ref: '#/components/schemas/Operator' description: >- A number operator: `is equal to`, `is not equal to`, `is greater than`, `is at least`, `is less than`, `is at most`, `is between`, `is not between` values: description: Two values for a range operator, one for the others. items: anyOf: - type: integer - type: number title: Values type: array date_range: description: When the events must have happened. discriminator: mapping: between: '#/components/schemas/BehaviorBetween' in_the_last: '#/components/schemas/BehaviorInTheLast' since: '#/components/schemas/BehaviorSince' propertyName: type oneOf: - $ref: '#/components/schemas/BehaviorInTheLast' - $ref: '#/components/schemas/BehaviorSince' - $ref: '#/components/schemas/BehaviorBetween' title: Date Range required: - event - measurement - operator - values - date_range title: BehaviorCriterion type: object CohortOperator: enum: - in - not in title: CohortOperator type: string Operator: description: |- The comparison a property filter applies. Which operators are valid depends on the property's `type`. enum: - is set - is not set - equals - does not equal - contains - does not contain - is equal to - is not equal to - is greater than - is at least - is less than - is at most - is between - is not between - is true - is false title: Operator type: string ListMatch: description: |- How a filter treats a list-valued property: match when any element passes, or only when all do. enum: - any - all title: ListMatch type: string CalculationType: description: >- The calculation a metric runs over its events or profiles. Separate from the interval aggregation, which rolls those calculated values up across time buckets. enum: - total_events - total_sessions - unique_users - daily_active_users - monthly_active_users - weekly_active_users title: CalculationType type: string BehaviorEventCount: additionalProperties: false properties: type: const: count title: Type type: string required: - type title: BehaviorEventCount type: object BehaviorPropertyStatistic: additionalProperties: false properties: type: const: property title: Type type: string statistic: description: The statistic of each user's values. enum: - sum - average - distinct_count - min - max title: Statistic type: string property: description: The event property the statistic is taken of. discriminator: mapping: event: '#/components/schemas/EventProperty' event_custom: '#/components/schemas/EventCustomProperty' lookup: '#/components/schemas/LookupProperty' profile: '#/components/schemas/ProfileProperty' profile_custom: '#/components/schemas/ProfileCustomProperty' propertyName: source oneOf: - $ref: '#/components/schemas/EventProperty' - $ref: '#/components/schemas/ProfileProperty' - $ref: '#/components/schemas/LookupProperty' - $ref: '#/components/schemas/EventCustomProperty' - $ref: '#/components/schemas/ProfileCustomProperty' title: Property required: - type - statistic - property title: BehaviorPropertyStatistic type: object BehaviorBetween: additionalProperties: false properties: type: const: between title: Type type: string start: anyOf: - description: >- Calendar date, YYYY-MM-DD, in the project's timezone. Covers the whole day. pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: >- Timestamp, YYYY-MM-DDTHH:mm, in the project's timezone. Covers the whole minute. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$ type: string description: Inclusive. title: Start end: anyOf: - description: >- Calendar date, YYYY-MM-DD, in the project's timezone. Covers the whole day. pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: >- Timestamp, YYYY-MM-DDTHH:mm, in the project's timezone. Covers the whole minute. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$ type: string description: Inclusive. title: End required: - type - start - end title: BehaviorBetween type: object BehaviorInTheLast: additionalProperties: false properties: type: const: in_the_last title: Type type: string value: description: Whole non-negative number of units before now. minimum: 0 title: Value type: integer unit: $ref: '#/components/schemas/TimeUnit' required: - type - value - unit title: BehaviorInTheLast type: object BehaviorSince: additionalProperties: false properties: type: const: since title: Type type: string start: anyOf: - description: >- Calendar date, YYYY-MM-DD, in the project's timezone. Covers the whole day. pattern: ^\d{4}-\d{2}-\d{2}$ type: string - description: >- Timestamp, YYYY-MM-DDTHH:mm, in the project's timezone. Covers the whole minute. pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$ type: string description: Inclusive. title: Start required: - type - start title: BehaviorSince type: object TimeUnit: enum: - minute - hour - day - week - month - quarter title: TimeUnit type: string responses: RequestValidationError: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/RequestValidationErrorResponse' Error: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ServiceAccountAuth: type: http description: >- This endpoint uses [Service Account](https://docs.mixpanel.com/reference/service-accounts#authenticating-with-a-service-account) authentication. scheme: basic ````