Unify Object Record Query Jobs API

openapi: 3.0.0
info:
  title: Unify Data Object Record 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: Object Record Query Jobs
paths:
  /data/v1/objects/{object_name}/query-jobs:
    post:
      operationId: create_object_record_query_job
      description: 'Start an asynchronous query job that exports records of an object. The

        query must `select` the attributes to return (optionally expanding

        single-reference attributes into nested records) and may filter with

        `where` / `metadata` and sort with `sort_by`; pairing an `updated_at`

        sort with a `metadata` filter enables incremental "changed since"

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

        results.'
      parameters:
      - name: object_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UObjects.UObjectName'
      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.
        '404':
          description: Response returned when the object being queried cannot be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBulkApiObjectRecordsJobObjectNotFoundResponse'
        '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:
      - Object Record Query Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkApiObjectRecordsJobRequest'
    get:
      operationId: list_object_record_query_jobs
      description: 'List query jobs previously created for an object, optionally filtered by

        status.'
      parameters:
      - name: object_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UObjects.UObjectName'
      - 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:
      - Object Record Query Jobs
  /data/v1/objects/{object_name}/query-jobs/{job_id}:
    get:
      operationId: get_object_record_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: object_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UObjects.UObjectName'
      - 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:
      - Object Record Query Jobs
  /data/v1/objects/{object_name}/query-jobs/{job_id}/cancel:
    post:
      operationId: cancel_object_record_query_job
      description: Cancel a query job. Only `IN_PROGRESS` jobs can be canceled.
      parameters:
      - name: object_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UObjects.UObjectName'
      - 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:
      - Object Record Query Jobs
  /data/v1/objects/{object_name}/query-jobs/{job_id}/results:
    get:
      operationId: get_object_record_query_job_results
      description: 'Get Bulk API job results. By default this returns JSON. Send

        `Accept: application/x-ndjson` to stream newline-delimited JSON.


        Each result row''s `created_at` / `updated_at` timestamps have millisecond

        precision.


        `attributes` is sparse: only the selected attributes are present, and a

        selected attribute whose value is null is omitted entirely. A missing key

        therefore means the value was null, not that it was unselected.'
      parameters:
      - name: object_name
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UObjects.UObjectName'
      - 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/BulkApiObjectRecordResult'
                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:
      - Object Record Query Jobs
components:
  schemas:
    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.
    BulkApiObjectRecordResult:
      type: object
      required:
      - object
      - id
      - created_at
      - updated_at
      - attributes
      properties:
        object:
          type: string
          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:
          type: object
          additionalProperties:
            anyOf:
            - allOf:
              - $ref: '#/components/schemas/UValues.UValue'
              nullable: true
            - type: object
              allOf:
              - $ref: '#/components/schemas/BulkApiObjectRecordResult'
              nullable: true
          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.'
      description: 'A single object record result row from a query job.


        Mirrors `UObjectRecord`, but widens `attributes` to allow nested records:

        a selected scalar attribute is a `UValue`, while a single-reference attribute

        expanded through a nested `select` resolves to a nested result record with

        this same shape. The recursion bottoms out at the `select` depth limit (see

        `SearchRecordsSelect`).'
    BulkApiObjectRecordsQuery:
      type: object
      required:
      - select
      properties:
        where:
          $ref: '#/components/schemas/SearchRecordsWhere'
        select:
          $ref: '#/components/schemas/SearchRecordsSelect'
        sort_by:
          $ref: '#/components/schemas/SearchRecordsMetadataSortBy'
        metadata:
          $ref: '#/components/schemas/SearchRecordsMetadataFilter'
      description: Query describing which object records to return and how to shape them.
    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.
    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.
    CreateBulkApiObjectRecordsJobObjectNotFoundResponse:
      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 the object being queried cannot be found.
    CreateBulkApiObjectRecordsJobRequest:
      type: object
      required:
      - query
      properties:
        query:
          $ref: '#/components/schemas/BulkApiObjectRecordsQuery'
      description: Request body for creating an object records Bulk API query job.
    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.
    SearchRecordsAttributeWhere:
      type: object
      required:
      - equals
      properties:
        equals:
          $ref: '#/components/schemas/UValues.UValue'
      description: 'Filter records by attribute value. The `equals` value must match the type of

        the attribute being filtered.'
    SearchRecordsMetadataFilter:
      type: object
      properties:
        created_at:
          $ref: '#/components/schemas/SearchRecordsTimestampFilter'
        updated_at:
          $ref: '#/components/schemas/SearchRecordsTimestampFilter'
      description: 'Filter records by base record timestamps (`created_at` / `updated_at`).


        Distinct from attribute `where` because these are record metadata rather than

        object attributes. Combined with a `created_at` / `updated_at` `sort_by`, this

        enables incremental queries that page through every record changed since a

        prior checkpoint.'
    SearchRecordsMetadataSortBy:
      type: object
      required:
      - field
      - direction
      properties:
        field:
          $ref: '#/components/schemas/SearchRecordsMetadataSortField'
        direction:
          $ref: '#/components/schemas/SearchRecordsSortDirection'
      description: 'Sort records by a base record field. Pairing a `created_at` / `updated_at`

        sort with the matching `metadata` filter enables incremental queries that

        page through every record changed since a prior checkpoint.'
    SearchRecordsMetadataSortField:
      type: string
      enum:
      - id
      - created_at
      - updated_at
      description: Base record field to sort by.
    SearchRecordsNestedSelect:
      type: object
      required:
      - select
      properties:
        select:
          $ref: '#/components/schemas/SearchRecordsSelect'
      description: 'Select the attributes of a referenced record reached through a

        single-reference attribute.'
    SearchRecordsSelect:
      type: object
      additionalProperties:
        anyOf:
        - type: boolean
          enum:
          - true
        - $ref: '#/components/schemas/SearchRecordsNestedSelect'
      description: 'Select the attributes to return for each record.


        Each key is an attribute API name on the queried object. A value of `true`

        returns the attribute directly, while `{ "select": ... }` expands a

        single-reference attribute and selects attributes on the referenced object.


        Nested selects may be at most three levels deep, counting the root select as

        level one (so the root plus at most two levels of nested reference selects).

        Requests exceeding this depth are rejected with a `400`.'
    SearchRecordsSortDirection:
      type: string
      enum:
      - ASCENDING
      - DESCENDING
      description: Direction in which to sort records.
    SearchRecords

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