Scale AI Jobs API

openapi: 3.2.0
info:
  title: Document Understanding Jobs API
  description: API for uploading and processing documents
  version: 0.6.0
security:
- ApiKey: []
  AccountId: []
tags:
- name: Jobs
  description: Operations related to monitoring jobs and their status
paths:
  /v1/projects/{project_id}/jobs/{job_id}:
    get:
      tags:
      - Jobs
      summary: Get Job
      description: 'Get a job by ID within the specified project.


        Args:

        project_id: Project ID that the job belongs to

        job_id: Job ID to retrieve


        Returns:

        JobEntity: The job details


        Raises:

        HTTPException: If project or job not found, or job doesn''t belong to project'
      operationId: get_job_v1_projects__project_id__jobs__job_id__get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobEntity'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/jobs:
    get:
      tags:
      - Jobs
      summary: List Jobs
      description: 'List all jobs for a project with token-based pagination and filtering.


        Args:

        project_id: Project ID that the jobs belong to

        pagination_params: Pagination parameters (page_size, continuation_token, sort_by, sort_order)

        filter_params: Filter parameters (ids, created_at, completed_at, status, operation)


        Returns:

        PaginatedItems or list of JobEntity instances


        Raises:

        HTTPException: If project not found'
      operationId: list_jobs_v1_projects__project_id__jobs_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by job IDs
          title: Ids
        description: Filter by job IDs
      - name: created_at_start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by creation time (start)
          title: Created At Start
        description: Filter by creation time (start)
      - name: created_at_end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by creation time (end)
          title: Created At End
        description: Filter by creation time (end)
      - name: completed_at_start
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by completion time (start)
          title: Completed At Start
        description: Filter by completion time (start)
      - name: completed_at_end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter by completion time (end)
          title: Completed At End
        description: Filter by completion time (end)
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/JobStatus'
          - type: 'null'
          description: Filter by job status
          title: Status
        description: Filter by job status
      - name: operation
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/JobOperationType'
          - type: 'null'
          description: Filter by job operation type
          title: Operation
        description: Filter by job operation type
      - name: page_size
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 100
            minimum: 1
          - type: 'null'
          description: Number of items per page
          title: Page Size
        description: Number of items per page
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Field to sort by
          title: Sort By
        description: Field to sort by
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          description: Sort order (asc or desc)
          title: Sort Order
        description: Sort order (asc or desc)
      - name: continuation_token
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination token
          title: Continuation Token
        description: Pagination token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/PaginatedItems_JobEntity_'
                - type: array
                  items:
                    $ref: '#/components/schemas/JobEntity'
                title: Response List Jobs V1 Projects  Project Id  Jobs Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/jobs/{job_id}/cancel:
    post:
      tags:
      - Jobs
      summary: Cancel Job
      description: 'Cancel a running or pending job.


        Idempotent: cancelling an already-cancelled job returns 200.

        For RUNNING jobs, returns 202 since the workflow handles cancellation

        asynchronously.'
      operationId: cancel_job_v1_projects__project_id__jobs__job_id__cancel_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Job cancelled (PENDING) or already cancelled (idempotent)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobEntity'
        '202':
          description: Cancellation requested for a RUNNING job
        '400':
          description: Job is in a terminal state (SUCCEEDED/FAILED)
        '404':
          description: Project or job not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/projects/{project_id}/jobs/{job_id}/updates:
    get:
      tags:
      - Jobs
      summary: Stream Job Updates
      description: 'Stream job trace spans as Server-Sent Events.


        Emits three event types:

        - ``trace_update``: a new or updated ``TraceSpan`` (JSON-serialised span)

        - ``job_status``: emitted when the database job status changes

        - ``done``: terminal event; the stream closes after this


        Clients should reconnect on transient network errors.'
      operationId: stream_job_updates_v1_projects__project_id__jobs__job_id__updates_get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          title: Project Id
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PaginatedItems_JobEntity_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/JobEntity'
          type: array
          title: Items
        total_count:
          type: integer
          title: Total Count
        next_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Token
        prev_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Prev Token
      type: object
      required:
      - items
      - total_count
      title: PaginatedItems[JobEntity]
    BatchChildJobInfo:
      properties:
        source_document_id:
          type: string
          title: Source Document Id
          description: Source document ID
        job_id:
          type: string
          title: Job Id
          description: Child job ID
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Status of the child job
        parse_result_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parse Result Id
          description: Parse result ID if succeeded
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if failed
      type: object
      required:
      - source_document_id
      - job_id
      - status
      title: BatchChildJobInfo
      description: Status of a single child job within a batch.
    JobOperationType:
      type: string
      enum:
      - parse
      - batch_parse
      - extract
      - research
      - vector_store
      - chunk
      - summarization
      - create_index
      - update_index
      title: JobOperationType
      description: Enum for job operation values.
    JobEntity:
      properties:
        id:
          type: string
          title: Id
          description: ID of the entity
        project_id:
          type: string
          title: Project Id
          description: ID of the project
        object:
          type: string
          const: job
          title: Object
          default: job
        operation:
          $ref: '#/components/schemas/JobOperationType'
          description: Operation type (e.g., 'parse')
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Current job status
        source_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Id
          description: Source document/file ID
        correlation_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Correlation Id
          description: Request correlation ID for tracing
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the job was created
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: When the job started processing
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: When the job completed
        result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result
          description: Job result payload when completed
        progress:
          anyOf:
          - $ref: '#/components/schemas/BatchParseProgress'
          - type: 'null'
          description: Live progress payload (used by batch jobs)
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if job failed
        history:
          anyOf:
          - items:
              $ref: '#/components/schemas/JobHistoryEvent'
            type: array
          - type: 'null'
          title: History
          description: Timeline of job execution events
      type: object
      required:
      - id
      - project_id
      - operation
      - status
      - created_at
      title: JobEntity
      description: Job response model representing an asynchronous operation.
    BatchParseProgress:
      properties:
        total:
          type: integer
          title: Total
          description: Total number of files in the batch
        succeeded:
          type: integer
          title: Succeeded
          description: Number of successfully parsed files
        failed:
          type: integer
          title: Failed
          description: Number of files that failed to parse
        cancelled:
          type: integer
          title: Cancelled
          description: Number of cancelled child jobs
        pending:
          type: integer
          title: Pending
          description: Number of files still pending (0 when job is terminal)
        child_jobs:
          items:
            $ref: '#/components/schemas/BatchChildJobInfo'
          type: array
          title: Child Jobs
          description: Per-child job status
      type: object
      required:
      - total
      - succeeded
      - failed
      - cancelled
      - pending
      - child_jobs
      title: BatchParseProgress
      description: Live progress tracking for a batch parse job.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    JobStatus:
      type: string
      enum:
      - pending
      - running
      - succeeded
      - partially_succeeded
      - failed
      - cancelled
      title: JobStatus
      description: Enum for job status values.
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
      description: 'Enum for project sort fields.

        Note that only non-nullable fields can be sorted by (for

        details, see: https://github.com/djrobstep/sqlakeyset?tab=readme-ov-file#limitations ).'
    JobHistoryEvent:
      properties:
        step:
          type: string
          title: Step
          description: Human-readable step name
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: When this event occurred
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
          description: Duration in milliseconds (for completed steps)
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: Event status (e.g., 'completed', 'failed')
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
          description: Additional event details
      type: object
      required:
      - step
      - timestamp
      title: JobHistoryEvent
      description: A single event in the job execution timeline.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
    AccountId:
      type: apiKey
      in: header
      name: x-selected-account-id
      description: Selected Account ID