Extend Batch Runs API

openapi: 3.2.0
info:
  title: Reference Batch Runs API
  version: 1.0.0
servers:
- url: https://api.extend.ai
  description: Production
- url: https://api.us2.extend.app
  description: Production US2
- url: https://api.eu1.extend.ai
  description: Production EU1
tags:
- name: batchRuns
paths:
  /batch_runs/{id}:
    get:
      operationId: batchRuns_get
      summary: Get Batch Run
      description: 'Retrieve the status of a batch run by its ID. The `status` field reflects the aggregate state of the batch.


        This is a unified endpoint that works for batches created via any of the batch submission endpoints (`POST /parse_runs/batch`, `POST /extract_runs/batch`, `POST /classify_runs/batch`, `POST /split_runs/batch`).


        | Status | Meaning |

        |---|---|

        | `PENDING` | Queued, not yet started |

        | `PROCESSING` | Runs are actively being processed |

        | `PROCESSED` | All runs have completed |

        | `FAILED` | The batch encountered a fatal error |

        | `CANCELLED` | The batch was cancelled |


        To retrieve individual run results, use the List endpoint for the relevant type filtered by `batchId`:

        - `GET /parse_runs?batchId={id}`

        - `GET /extract_runs?batchId={id}`

        - `GET /classify_runs?batchId={id}`

        - `GET /split_runs?batchId={id}`'
      tags:
      - batchRuns
      parameters:
      - name: id
        in: path
        description: 'The unique identifier of the batch processor run to retrieve.


          Example: `"bpr_Xj8mK2pL9nR4vT7qY5wZ"`

          '
        required: true
        schema:
          type: string
      - name: x-extend-api-version
        in: header
        description: API version to use for the request. If you're using an SDK, you can ignore this parameter. If you are not using an SDK and do not specify a version, you will either receive a `400 Bad Request` or be set to a previous legacy version. See [API Versioning](https://docs.extend.ai/2026-02-09/api-reference/api-versioning) for more details.
        required: false
        schema:
          type: string
          enum:
          - '2026-02-09'
          default: '2026-02-09'
      responses:
        '200':
          description: Successfully retrieved batch processor run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRun'
        '400':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '402':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: 'Standard error response format for all Extend API errors.


            See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - BearerAuth: []
components:
  schemas:
    BatchRun:
      type: object
      properties:
        object:
          $ref: '#/components/schemas/BatchRunObject'
          description: The type of object. Always `"batch_run"`.
        id:
          type: string
          description: 'The unique identifier for this batch run.


            Example: `"bpr_Xj8mK2pL9nR4vT7qY5wZ"`

            '
        status:
          $ref: '#/components/schemas/BatchRunStatus'
        runCount:
          type: integer
          description: The number of individual runs in this batch.
        createdAt:
          $ref: '#/components/schemas/CreatedAt'
      required:
      - object
      - id
      - status
      - runCount
      - createdAt
      description: 'A batch run represents a batch of files submitted for processing via one of the batch endpoints (`POST /parse_runs/batch`, `POST /extract_runs/batch`, `POST /classify_runs/batch`, or `POST /split_runs/batch`). Use `GET /batch_runs/{id}` to poll the status.


        **Note:** This object is not used for workflow batch runs. See `POST /workflow_runs/batch` for workflow batching.

        '
      title: BatchRun
    CreatedAt:
      type: string
      format: date-time
      description: 'The time (in UTC) at which the object was created. Will follow the RFC 3339 format.


        Example: `"2024-03-21T16:45:00Z"`

        '
      title: CreatedAt
    BatchRunStatus:
      type: string
      enum:
      - PENDING
      - PROCESSING
      - PROCESSED
      - FAILED
      - CANCELLED
      description: 'The status of a batch run:

        * `"PENDING"` - The batch has been created and is waiting to be processed

        * `"PROCESSING"` - The batch is currently being processed

        * `"PROCESSED"` - All runs in the batch have completed successfully

        * `"FAILED"` - The batch failed to process

        * `"CANCELLED"` - The batch was cancelled

        '
      title: BatchRunStatus
    BatchRunObject:
      type: string
      enum:
      - batch_run
      description: The type of object. Always `"batch_run"`.
      title: BatchRunObject
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling.
        message:
          type: string
          description: "Human-readable error message suitable for displaying to developers. \nDo not rely on the exact text of this message as it may change.\n"
        retryable:
          type: boolean
          description: 'Whether the request can be retried. When true, retry with exponential backoff.

            When false, fix the underlying issue before retrying.

            '
        requestId:
          type: string
          description: "Unique request identifier for support purposes. Always include this \nwhen contacting Extend support about an error.\n"
        docUrl:
          type: string
          description: Link to relevant documentation when one is available.
      required:
      - code
      - message
      - retryable
      description: 'Standard error response format for all Extend API errors.


        See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

        '
      title: ApiError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Extend
  source: https://docs.extend.ai/openapi/api-reference.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)