Unify Event Query Jobs API

openapi: 3.0.0
info:
  title: Unify Data Event Query Jobs API
  summary: Interact with objects, attributes, and records within the Unify platform.
  version: '1'
  termsOfService: https://www.unifygtm.com/legal/terms-and-conditions
  contact:
    name: Unify Support
    url: https://www.unifygtm.com/support
    email: support@unifygtm.com
servers:
- url: https://api.unifygtm.com
  variables: {}
security:
- ApiKeyAuth: []
tags:
- name: Event Query Jobs
paths:
  /data/v1/events/query-jobs:
    post:
      operationId: create_event_query_job
      description: 'Start an asynchronous query job that exports analytics events — website

        and product activity (`page`, `track`, `identify`) with any revealed

        company and person embedded in each row. Events are immutable, so filter

        on `timestamp` for incremental exports; omitting `filter` exports all

        events. Poll the job until it is `FINISHED`, then page through the

        results.'
      parameters: []
      responses:
        '201':
          description: Response returned when creating a Bulk API query job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBulkApiJobSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Event Query Jobs
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkApiEventsJobRequest'
    get:
      operationId: list_event_query_jobs
      description: List event query jobs, optionally filtered by status.
      parameters:
      - name: cursor
        in: query
        required: false
        description: Opaque cursor returned by the previous page.
        schema:
          type: string
        explode: false
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        explode: false
      - name: status
        in: query
        required: false
        description: Filter jobs by status.
        schema:
          $ref: '#/components/schemas/BulkApiJobStatus'
        explode: false
      responses:
        '200':
          description: Response returned when listing Bulk API jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBulkApiJobsSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Event Query Jobs
  /data/v1/events/query-jobs/{job_id}:
    get:
      operationId: get_event_query_job
      description: 'Get a query job''s status. Poll until the status is terminal; results are

        available once the job is `FINISHED`. Jobs expire 24 hours after

        creation.'
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response returned when fetching a Bulk API job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '404':
          description: Response returned when a Bulk API job cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobNotFoundResponse'
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Event Query Jobs
  /data/v1/events/query-jobs/{job_id}/cancel:
    post:
      operationId: cancel_event_query_job
      description: Cancel a query job. Only `IN_PROGRESS` jobs can be canceled.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response returned when canceling a Bulk API job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelBulkApiJobSuccessResponse'
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '404':
          description: Response returned when a Bulk API job cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobNotFoundResponse'
        '409':
          description: Response returned when a Bulk API job is not cancelable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelBulkApiJobNotCancelableResponse'
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Event Query Jobs
  /data/v1/events/query-jobs/{job_id}/results:
    get:
      operationId: get_event_query_job_results
      description: 'Get Bulk API job results. By default this returns JSON. Send

        `Accept: application/x-ndjson` to stream newline-delimited JSON.'
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
        explode: false
      - name: page_size
        in: query
        required: false
        description: 'Maximum is 2,000 for JSON responses and 10,000 when `Accept` is

          `application/x-ndjson`.'
        schema:
          type: integer
          minimum: 1
          maximum: 10000
        explode: false
      responses:
        '200':
          description: Successful response returned when fetching completed Bulk API job results.
          headers:
            x-total:
              required: false
              description: Total result count. Present for NDJSON responses.
              schema:
                type: integer
            x-page:
              required: false
              description: Result page number. Present for NDJSON responses.
              schema:
                type: integer
            x-page-size:
              required: false
              description: Result page size. Present for NDJSON responses.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                - total
                - page
                - page_size
                - data
                properties:
                  total:
                    type: integer
                  page:
                    type: integer
                  page_size:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UEvent'
                description: Successful response returned when fetching completed Bulk API job results.
            application/x-ndjson:
              schema:
                type: string
        '400':
          description: Response for any operation that results in a bad request error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: string
                    enum:
                    - bad_request
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/UResponses.BadRequestError'
                  message:
                    type: string
                description: Response for any operation that results in a bad request error.
        '401':
          description: Response for any operation that results in an unauthorized error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - unauthorized
                  message:
                    type: string
                description: Response for any operation that results in an unauthorized error.
        '404':
          description: Response returned when a Bulk API job cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobNotFoundResponse'
        '409':
          description: Response returned when Bulk API job results are not ready yet.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/GetBulkApiJobResultsNotReadyResponse'
                - $ref: '#/components/schemas/GetBulkApiJobResultsFailedResponse'
                - $ref: '#/components/schemas/GetBulkApiJobResultsCanceledResponse'
        '410':
          description: Response returned when Bulk API job results have expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobResultsExpiredResponse'
        '413':
          description: Response returned when a requested Bulk API results page is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkApiJobResultsPayloadTooLargeResponse'
        '429':
          description: Response for any operation that exceeds a rate limit.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - rate_limited
                  message:
                    type: string
                description: Response for any operation that exceeds a rate limit.
        '500':
          description: Response for any operation that results in an internal server error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - error
                  message:
                    type: string
                description: Response for any operation that results in an internal server error.
      tags:
      - Event Query Jobs
components:
  schemas:
    BulkApiDatetimeRangeFilter:
      type: object
      properties:
        gt:
          type: string
        gte:
          type: string
        lt:
          type: string
        lte:
          type: string
      description: 'Datetime range filter. At least one bound must be provided. `gt` is mutually

        exclusive with `gte`, and `lt` is mutually exclusive with `lte`.'
    BulkApiEventsQueryFilter:
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/BulkApiDatetimeRangeFilter'
        id:
          anyOf:
          - type: object
            required:
            - in
            properties:
              in:
                type: array
                items:
                  type: string
                minItems: 1
              not_in:
                type: array
                items:
                  type: string
                minItems: 1
            description: Filter matching values included in a set.
          - type: object
            required:
            - not_in
            properties:
              in:
                type: array
                items:
                  type: string
                minItems: 1
              not_in:
                type: array
                items:
                  type: string
                minItems: 1
            description: Filter matching values excluded from a set.
        type:
          anyOf:
          - type: object
            required:
            - in
            properties:
              in:
                type: array
                items:
                  $ref: '#/components/schemas/EventType'
                minItems: 1
              not_in:
                type: array
                items:
                  $ref: '#/components/schemas/EventType'
                minItems: 1
            description: Filter matching values included in a set.
          - type: object
            required:
            - not_in
            properties:
              in:
                type: array
                items:
                  $ref: '#/components/schemas/EventType'
                minItems: 1
              not_in:
                type: array
                items:
                  $ref: '#/components/schemas/EventType'
                minItems: 1
            description: Filter matching values excluded from a set.
        session:
          $ref: '#/components/schemas/BulkApiUuidFilter'
        company:
          $ref: '#/components/schemas/BulkApiUuidFilter'
        person:
          $ref: '#/components/schemas/BulkApiUuidFilter'
        domain:
          type: string
      description: 'Filters accepted when querying events. Events are immutable, so the natural

        cursor is `timestamp`, which is also the only datetime field filterable here.'
    BulkApiJob:
      type: object
      required:
      - job_id
      - status
      - total_rows
      - error_code
      - created_at
      - expires_at
      - canceled_at
      properties:
        job_id:
          type: string
        status:
          $ref: '#/components/schemas/BulkApiJobStatus'
        total_rows:
          type: integer
          nullable: true
        error_code:
          type: string
          nullable: true
        created_at:
          type: string
        expires_at:
          type: string
        canceled_at:
          type: string
          nullable: true
      description: Bulk API job representation.
    BulkApiJobStatus:
      type: string
      enum:
      - IN_PROGRESS
      - FINISHED
      - FAILED
      - EXPIRED
      - CANCELED
      description: Status of an asynchronous Bulk API job.
    BulkApiUuidFilter:
      type: object
      required:
      - id
      properties:
        id:
          type: string
      description: Filter matching a resource by ID.
    CancelBulkApiJobNotCancelableResponse:
      type: object
      allOf:
      - type: object
        required:
        - status
        - message
        properties:
          status:
            type: string
            enum:
            - job_not_cancelable
          message:
            type: string
        description: Response for any operation that results in a conflict error.
      description: Response returned when a Bulk API job is not cancelable.
    CancelBulkApiJobSuccessResponse:
      type: object
      required:
      - job_id
      - status
      properties:
        job_id:
          type: string
        status:
          type: string
          enum:
          - CANCELED
      description: Response returned when canceling a Bulk API job.
    CreateBulkApiEventsJobRequest:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/BulkApiEventsQueryFilter'
      description: Request body for creating an events Bulk API query job.
    CreateBulkApiJobSuccessResponse:
      type: object
      required:
      - job_id
      - status
      - expires_at
      properties:
        job_id:
          type: string
        status:
          type: string
          enum:
          - IN_PROGRESS
        expires_at:
          type: string
      description: Response returned when creating a Bulk API query job.
    EventType:
      type: string
      enum:
      - page
      - track
      - identify
      description: Canonical, source-agnostic event type.
    GetBulkApiJobNotFoundResponse:
      type: object
      allOf:
      - type: object
        required:
        - status
        - message
        properties:
          status:
            type: string
            enum:
            - not_found
          message:
            type: string
        description: Response for any operation that results in a not found error.
      description: Response returned when a Bulk API job cannot be found.
    GetBulkApiJobResultsCanceledResponse:
      type: object
      allOf:
      - type: object
        required:
        - status
        - message
        properties:
          status:
            type: string
            enum:
            - results_canceled
          message:
            type: string
        description: Response for any operation that results in a conflict error.
      description: Response returned when a Bulk API job was canceled and has no results.
    GetBulkApiJobResultsExpiredResponse:
      type: object
      required:
      - status
      - message
      properties:
        status:
          type: string
          enum:
          - results_expired
        message:
          type: string
      description: Response returned when Bulk API job results have expired.
    GetBulkApiJobResultsFailedResponse:
      type: object
      allOf:
      - type: object
        required:
        - status
        - message
        properties:
          status:
            type: string
            enum:
            - results_failed
          message:
            type: string
        description: Response for any operation that results in a conflict error.
      description: Response returned when a Bulk API job failed and has no results.
    GetBulkApiJobResultsNotReadyResponse:
      type: object
      allOf:
      - type: object
        required:
        - status
        - message
        properties:
          status:
            type: string
            enum:
            - results_not_ready
          message:
            type: string
        description: Response for any operation that results in a conflict error.
      description: Response returned when Bulk API job results are not ready yet.
    GetBulkApiJobResultsPayloadTooLargeResponse:
      type: object
      required:
      - status
      - message
      properties:
        status:
          type: string
          enum:
          - results_page_too_large
        message:
          type: string
      description: Response returned when a requested Bulk API results page is too large.
    GetBulkApiJobSuccessResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/BulkApiJob'
      description: Response returned when fetching a Bulk API job.
    ListBulkApiJobsSuccessResponse:
      type: object
      required:
      - jobs
      - next_cursor
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/BulkApiJob'
        next_cursor:
          type: string
          nullable: true
      description: Response returned when listing Bulk API jobs.
    UEvent:
      type: object
      required:
      - id
      - original_event_id
      - timestamp
      - type
      - name
      - properties
      - anonymous_id
      - session_id
      - company
      - person
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/UValues.UUuid'
          description: Unique identifier for the event.
        original_event_id:
          type: string
          description: 'Identifier assigned to the event by the upstream source that produced it

            (e.g. a Segment `messageId`, a PostHog event ID, or a Unify Tag activity

            ID).'
        timestamp:
          allOf:
          - $ref: '#/components/schemas/UValues.UDatetime'
          description: 'Time the event occurred. Events are immutable, so this is the natural

            cursor for incremental syncs.'
        type:
          allOf:
          - $ref: '#/components/schemas/EventType'
          description: Canonical event type.
        name:
          type: string
          nullable: true
          description: Human-readable event name, or `null` when unset.
        properties:
          type: object
          additionalProperties: {}
          nullable: true
          description: 'Event properties: custom track-event properties merged with page context

            (`domain`, `path`, `referrer_domain`, `referrer_path`, `query`) and UTM

            parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`,

            `utm_content`). Keys with no value are omitted, and the whole object is

            `null` when no properties are present.'
        anonymous_id:
          type: string
          description: Anonymous identifier assigned to the visitor by the upstream source.
        session_id:
          allOf:
          - $ref: '#/components/schemas/UValues.UUuid'
          description: Identifier of the session the event belongs to.
        company:
          type: object
          allOf:
          - $ref: '#/components/schemas/UObjects.UCompany'
          nullable: true
          description: Revealed company associated with the visitor, or `null` when unresolved.
        person:
          type: object
          allOf:
          - $ref: '#/components/schemas/UObjects.UPerson'
          nullable: true
          description: Revealed person associated with the visitor, or `null` when unresolved.
      description: 'A flat, denormalized event row returned by an event Bulk API

        query job.


        Unlike object records, events are not wrapped in the `object` / `attributes`

        envelope. Page, session, and UTM context are folded into `properties`, while

        the revealed `company` / `person` are embedded directly on the row as full

        object records (`null` when the visitor has no revealed company / person).'
    UObjects.UCompany:
      type: object
      required:
      - object
      - id
      - created_at
      - updated_at
      - attributes
      properties:
        object:
          type: string
          enum:
          - company
          description: The API name of the object this record is an instance of.
          readOnly: true
        id:
          allOf:
          - $ref: '#/components/schemas/UValues.UUuid'
          description: Unique UUID identifier for the record.
          readOnly: true
        created_at:
          type: string
          format: date-time
          description: Date and time the record was created.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: Date and time the record was last updated.
          readOnly: true
        attributes:
          allOf:
          - $ref: '#/components/schemas/UObjects.UCompanyAttributes'
          description: 'Attribute values for the record. Each key is the API name of the attribute

            and each value is the corresponding attribute value for the record.'
    UObjects.UCompanyAttributes:
      type: object
      required:
      - domain
      properties:
        address:
          allOf:
          - $ref: '#/components/schemas/UValues.UAddres

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unify/refs/heads/main/openapi/unify-event-query-jobs-api-openapi.yml