Scale AI Tasks API

openapi: 3.2.0
info:
  title: Scale Ai Tasks API
  version: '1.0'
  description: 'Operations tagged Tasks across 2 of this provider''s published API definitions: scale-ai-agentex-openapi.json, scale-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.scale.com/v1
  description: Scale REST API (v1)
tags:
- name: Tasks
paths:
  /tasks/{task_id}:
    get:
      tags:
      - Tasks
      summary: Get Task by ID
      description: Get a task by its unique ID.
      operationId: get_task_tasks__task_id__get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      - name: relationships
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TaskRelationships'
          title: Relationships
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Tasks
      summary: Delete Task by ID
      description: Delete a task by its unique ID.
      operationId: delete_task_tasks__task_id__delete
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Tasks
      summary: Update Task by ID
      description: Update mutable fields for a task by its unique ID.
      operationId: update_task_tasks__task_id__put
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/name/{task_name}:
    get:
      tags:
      - Tasks
      summary: Get Task by Name
      description: Get a task by its unique name.
      operationId: get_task_by_name_tasks_name__task_name__get
      parameters:
      - name: task_name
        in: path
        required: true
        schema:
          type: string
          title: Task Name
      - name: relationships
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TaskRelationships'
          title: Relationships
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Tasks
      summary: Delete Task by Name
      description: Delete a task by its unique name.
      operationId: delete_task_by_name_tasks_name__task_name__delete
      parameters:
      - name: task_name
        in: path
        required: true
        schema:
          type: string
          title: Task Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Tasks
      summary: Update Task by Name
      description: Update mutable fields for a task by its unique Name.
      operationId: update_task_by_name_tasks_name__task_name__put
      parameters:
      - name: task_name
        in: path
        required: true
        schema:
          type: string
          title: Task Name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks:
    get:
      tags:
      - Tasks
      summary: List Tasks
      description: List tasks. Returns a lean summary per task and omits `params`; fetch GET /tasks/{task_id} for the full record including `params`.
      operationId: list_tasks_tasks_get
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
      - name: agent_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/TaskStatus'
          - type: 'null'
          description: Filter tasks by status (e.g. RUNNING, COMPLETED).
          title: Status
        description: Filter tasks by status (e.g. RUNNING, COMPLETED).
      - name: task_metadata
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'JSON-encoded object used to filter tasks via JSONB containment. Example: {"created_by_user_id": "abc-123"}.'
          title: Task Metadata
        description: 'JSON-encoded object used to filter tasks via JSONB containment. Example: {"created_by_user_id": "abc-123"}.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: page_number
        in: query
        required: false
        schema:
          type: integer
          default: 1
          title: Page Number
      - name: order_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Order By
      - name: order_direction
        in: query
        required: false
        schema:
          type: string
          default: desc
          title: Order Direction
      - name: relationships
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TaskRelationships'
          title: Relationships
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaskSummary'
                title: Response List Tasks Tasks Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/complete:
    post:
      tags:
      - Tasks
      summary: Complete Task
      description: Mark a running task as completed.
      operationId: complete_task_tasks__task_id__complete_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TaskStatusReasonRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/fail:
    post:
      tags:
      - Tasks
      summary: Fail Task
      description: Mark a running task as failed.
      operationId: fail_task_tasks__task_id__fail_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TaskStatusReasonRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/cancel:
    post:
      tags:
      - Tasks
      summary: Cancel Task
      description: Mark a running task as canceled.
      operationId: cancel_task_tasks__task_id__cancel_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TaskStatusReasonRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/interrupt:
    post:
      tags:
      - Tasks
      summary: Interrupt Task
      description: Stop the in-flight turn without terminating the task. Transitions a running task to the non-terminal INTERRUPTED status; the task stays continuable and the next message or event resumes it.
      operationId: interrupt_task_tasks__task_id__interrupt_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TaskStatusReasonRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/terminate:
    post:
      tags:
      - Tasks
      summary: Terminate Task
      description: Mark a running task as terminated.
      operationId: terminate_task_tasks__task_id__terminate_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TaskStatusReasonRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/timeout:
    post:
      tags:
      - Tasks
      summary: Timeout Task
      description: Mark a running task as timed out.
      operationId: timeout_task_tasks__task_id__timeout_post
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/TaskStatusReasonRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/stream:
    get:
      tags:
      - Tasks
      summary: Stream Task Events by ID
      description: Stream events for a task by its unique ID.
      operationId: stream_task_events_tasks__task_id__stream_get
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/name/{task_name}/stream:
    get:
      tags:
      - Tasks
      summary: Stream Task Events by Name
      description: Stream events for a task by its unique name.
      operationId: stream_task_events_by_name_tasks_name__task_name__stream_get
      parameters:
      - name: task_name
        in: path
        required: true
        schema:
          type: string
          title: Task Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /tasks/{task_id}/query/{query_name}:
    get:
      tags:
      - Tasks
      summary: Query Task Workflow
      description: Query a Temporal workflow associated with a task for its current state.
      operationId: query_task_workflow_tasks__task_id__query__query_name__get
      parameters:
      - name: query_name
        in: path
        required: true
        schema:
          type: string
          title: Query Name
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Query Task Workflow Tasks  Task Id  Query  Query Name  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /task:
    post:
      summary: Create a task
      operationId: createTask
      tags:
      - Tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project:
                  type: string
                instruction:
                  type: string
                attachment:
                  type: string
      responses:
        '200':
          description: Task created.
      security:
      - BasicAuth: []
    servers:
    - url: https://api.scale.com/v1
      description: Scale REST API (v1)
  /task/{task_id}:
    parameters:
    - name: task_id
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Retrieve a task
      operationId: retrieveTask
      tags:
      - Tasks
      responses:
        '200':
          description: A task.
      security:
      - BasicAuth: []
    servers:
    - url: https://api.scale.com/v1
      description: Scale REST API (v1)
  /task/{task_id}/cancel:
    post:
      summary: Cancel a task
      operationId: cancelTask
      tags:
      - Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Task canceled.
      security:
      - BasicAuth: []
    servers:
    - url: https://api.scale.com/v1
      description: Scale REST API (v1)
  /task/{task_id}/setMetadata:
    post:
      summary: Set task metadata
      operationId: setTaskMetadata
      tags:
      - Tasks
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Metadata updated.
      security:
      - BasicAuth: []
    servers:
    - url: https://api.scale.com/v1
      description: Scale REST API (v1)
components:
  schemas:
    UpdateTaskRequest:
      properties:
        task_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: If provided, replaces task_metadata with this value
        merge_params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Optional shallow-merge patch applied to the task's params column. Top-level keys overwrite; pass full nested objects to change subfields.
      type: object
      title: UpdateTaskRequest
    TaskStatus:
      type: string
      enum:
      - CANCELED
      - COMPLETED
      - FAILED
      - RUNNING
      - INTERRUPTED
      - TERMINATED
      - TIMED_OUT
      - DELETED
      title: TaskStatus
    ACPType:
      type: string
      enum:
      - sync
      - async
      - agentic
      title: ACPType
    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
    TaskStatusReasonRequest:
      properties:
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Optional reason for the status change
      type: object
      title: TaskStatusReasonRequest
    TaskRelationships:
      type: string
      enum:
      - agents
      title: TaskRelationships
      description: Task relationships that can be loaded
    AgentInputType:
      type: string
      enum:
      - text
      - json
      title: AgentInputType
    AgentStatus:
      type: string
      enum:
      - Ready
      - Failed
      - Unknown
      - Deleted
      - Unhealthy
      - BuildOnly
      title: AgentStatus
    TaskSummary:
      properties:
        id:
          type: string
          title: Unique Task ID
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Unique name of the task
        status:
          anyOf:
          - $ref: '#/components/schemas/TaskStatus'
          - type: 'null'
          title: The current status of the task
        status_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: The reason for the current task status
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task was last updated
        cleaned_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task's content was cleaned for retention compliance; null when active
        task_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task metadata
        agents:
          anyOf:
          - items:
              $ref: '#/components/schemas/Agent'
            type: array
          - type: 'null'
          title: Agents associated with this task (only populated when 'agents' view is requested)
      type: object
      required:
      - id
      title: TaskSummary
      description: 'Lean list-response shape. Omits `params` (the arbitrary create-time

        payload, which can carry per-caller secrets and PII); fetch GET /tasks/{id}

        for the full record.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Task:
      properties:
        id:
          type: string
          title: Unique Task ID
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Unique name of the task
        status:
          anyOf:
          - $ref: '#/components/schemas/TaskStatus'
          - type: 'null'
          title: The current status of the task
        status_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: The reason for the current task status
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task was last updated
        cleaned_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task's content was cleaned for retention compliance; null when active
        params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task parameters
        task_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task metadata
      type: object
      required:
      - id
      title: Task
    TaskResponse:
      properties:
        id:
          type: string
          title: Unique Task ID
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Unique name of the task
        status:
          anyOf:
          - $ref: '#/components/schemas/TaskStatus'
          - type: 'null'
          title: The current status of the task
        status_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: The reason for the current task status
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task was created
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task was last updated
        cleaned_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: The timestamp when the task's content was cleaned for retention compliance; null when active
        params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task parameters
        task_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task metadata
        agents:
          anyOf:
          - items:
              $ref: '#/components/schemas/Agent'
            type: array
          - type: 'null'
          title: Agents associated with this task (only populated when 'agent' view is requested)
      type: object
      required:
      - id
      title: TaskResponse
      description: Task response model with optional related data based on relationships
    DeleteResponse:
      properties:
        id:
          type: string
          title: Id
        message:
          type: string
          title: Message
      type: object
      required:
      - id
      - message
      title: DeleteResponse
    Agent:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the agent.
        name:
          type: string
          title: Name
          description: The unique name of the agent.
        description:
          type: string
          title: Description
          description: The description of the action.
        status:
          $ref: '#/components/schemas/AgentStatus'
          description: The status of the action, indicating if it's building, ready, failed, etc.
          default: Unknown
        acp_type:
          $ref: '#/components/schemas/ACPType'
          description: The type of the ACP Server (Either sync or async)
        status_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Status Reason
          description: The reason for the status of the action.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The timestamp when the agent was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: The timestamp when the agent was last updated
        registration_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Registration Metadata
          description: The metadata for the agent's registration.
        registered_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Registered At
          description: The timestamp when the agent was last registered
        agent_input_type:
          anyOf:
          - $ref: '#/components/schemas/AgentInputType'
          - type: 'null'
          description: The type of input the agent expects.
        production_deployment_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Production Deployment Id
          description: ID of the current production deployment.
      type: object
      required:
      - id
      - name
      - description
      - acp_type
      - created_at
      - updated_at
      title: Agent
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication. Use your Scale API key (live or sandbox) as

        the username and leave the password blank.

        '
x-refined-from:
- scale-ai-agentex-openapi.json
- scale-ai-openapi.yml