> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morphllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Batches

> Page through your batches at /v1/batches

## Overview

Lists the key's batches, newest first. `after` is an integer offset, not an object id: add `limit` to it for each next page.


## OpenAPI

````yaml GET /v1/batches
openapi: 3.1.0
info:
  title: Morph API
  version: 1.2.0
  description: >-
    The Morph public API at api.morphllm.com: OpenAI- and Anthropic-compatible
    inference (chat completions, messages), the Batch API, Fast Apply code
    editing, Compact context compression, Reflex classification, and
    fine-tuning. Model ids, prices, and context windows are served live at
    https://www.morphllm.com/api/models/json.
  contact:
    name: Morph
    url: https://morphllm.com
    email: info@morphllm.com
  license:
    name: Proprietary
    url: https://morphllm.com/privacy/tos
servers:
  - url: https://api.morphllm.com
    description: Production
security: []
tags:
  - name: chat
    description: >-
      OpenAI- and Anthropic-compatible chat inference, including Fast Apply and
      WarpGrep models.
  - name: compact
    description: Context compression for long agent conversations.
  - name: reflex
    description: 'Per-turn classifiers: realtime prediction and batches.'
  - name: fine-tuning
    description: Reflex fine-tuning job lifecycle.
  - name: batch
    description: >-
      OpenAI-compatible Batch API: upload a JSONL file, run it at half price,
      download the results.
  - name: models
    description: Model listing and management.
  - name: telemetry
    description: Usage reporting hooks.
paths:
  /v1/batches:
    get:
      tags:
        - batch
      summary: List batches
      description: Page through the key's batches, newest first.
      operationId: listBatches
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            description: Batches per page. Default 20, max 100.
            example: 20
          required: false
          description: How many batches to return in this page.
          name: limit
          in: query
        - schema:
            type: integer
            minimum: 0
            description: >-
              Offset cursor: how many batches to skip. Add `limit` to it for
              each next page.
            example: 20
          required: false
          description: >-
            Pagination offset into your batches. An integer count, not an object
            id, so page manually rather than with the SDK auto-paginator.
          name: after
          in: query
      responses:
        '200':
          description: The requested page of batches.
          content:
            application/json:
              example:
                object: list
                data:
                  - id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
                    object: batch
                    endpoint: /v1/chat/completions
                    input_file_id: file_9c2c1c3e-5b6a-4f0e-8d0f-2a1b3c4d5e6f
                    completion_window: 24h
                    metadata:
                      job: nightly-summaries
                    created_at: 1780000000
                    status: completed
                    model: morph-glm53flash
                    output_file_id: file_0e7d6c5b-4a39-4281-9f7e-6d5c4b3a2918
                    error_file_id: file_7f6e5d4c-3b2a-4190-8e7d-6c5b4a392817
                    in_progress_at: 1780000012
                    finalizing_at: 1780005460
                    completed_at: 1780005470
                    failed_at: null
                    expired_at: null
                    expires_at: 1780086400
                    cancelling_at: null
                    cancelled_at: null
                    request_counts:
                      total: 2
                      completed: 2
                      failed: 0
                    errors: null
                    usage:
                      input_tokens: 824
                      input_tokens_details:
                        cached_tokens: 0
                      output_tokens: 36
                      output_tokens_details:
                        reasoning_tokens: 0
                      total_tokens: 860
                first_id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
                last_id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
                has_more: false
              schema:
                $ref: '#/components/schemas/BatchList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    BatchList:
      type: object
      properties:
        object:
          type: string
          description: Object type of a batch page, always `list`.
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Batch'
          description: Batches in this page.
          example:
            - id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
              object: batch
              endpoint: /v1/chat/completions
              input_file_id: file_9c2c1c3e-5b6a-4f0e-8d0f-2a1b3c4d5e6f
              completion_window: 24h
              metadata:
                job: nightly-summaries
              created_at: 1780000000
              status: completed
              model: morph-glm53flash
              output_file_id: file_0e7d6c5b-4a39-4281-9f7e-6d5c4b3a2918
              error_file_id: file_7f6e5d4c-3b2a-4190-8e7d-6c5b4a392817
              in_progress_at: 1780000012
              finalizing_at: 1780005460
              completed_at: 1780005470
              failed_at: null
              expired_at: null
              expires_at: 1780086400
              cancelling_at: null
              cancelled_at: null
              request_counts:
                total: 2
                completed: 2
                failed: 0
              errors: null
              usage:
                input_tokens: 824
                input_tokens_details:
                  cached_tokens: 0
                output_tokens: 36
                output_tokens_details:
                  reasoning_tokens: 0
                total_tokens: 860
        first_id:
          type:
            - string
            - 'null'
          description: >-
            Id of the first batch in this page, or `null` when the page is
            empty.
          example: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
        last_id:
          type:
            - string
            - 'null'
          description: Id of the last batch in this page, or `null` when the page is empty.
          example: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
        has_more:
          type: boolean
          description: Whether more batches exist after this page.
          example: false
      required:
        - object
        - data
        - first_id
        - last_id
        - has_more
      description: A page of batches.
      example:
        object: list
        data:
          - id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
            object: batch
            endpoint: /v1/chat/completions
            input_file_id: file_9c2c1c3e-5b6a-4f0e-8d0f-2a1b3c4d5e6f
            completion_window: 24h
            metadata:
              job: nightly-summaries
            created_at: 1780000000
            status: completed
            model: morph-glm53flash
            output_file_id: file_0e7d6c5b-4a39-4281-9f7e-6d5c4b3a2918
            error_file_id: file_7f6e5d4c-3b2a-4190-8e7d-6c5b4a392817
            in_progress_at: 1780000012
            finalizing_at: 1780005460
            completed_at: 1780005470
            failed_at: null
            expired_at: null
            expires_at: 1780086400
            cancelling_at: null
            cancelled_at: null
            request_counts:
              total: 2
              completed: 2
              failed: 0
            errors: null
            usage:
              input_tokens: 824
              input_tokens_details:
                cached_tokens: 0
              output_tokens: 36
              output_tokens_details:
                reasoning_tokens: 0
              total_tokens: 860
        first_id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
        last_id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
        has_more: false
    Batch:
      type: object
      properties:
        id:
          type: string
          description: Batch identifier, `batch_` prefixed.
          example: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
        object:
          type: string
          description: Object type, always `batch`.
          example: batch
        endpoint:
          type: string
          description: The endpoint every line targets. Always `/v1/chat/completions`.
          example: /v1/chat/completions
        input_file_id:
          type: string
          description: The file the batch reads its requests from.
          example: file_9c2c1c3e-5b6a-4f0e-8d0f-2a1b3c4d5e6f
        completion_window:
          type: string
          description: >-
            Always `24h`. Requests still queued when the window closes are
            written to the error file as `batch_expired`.
          example: 24h
        metadata:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: The key-value pairs you attached at creation, or `null`.
          example:
            job: nightly-summaries
        created_at:
          type: integer
          description: Unix timestamp (seconds) for when the batch was created.
          example: 1780000000
        status:
          type: string
          enum:
            - validating
            - in_progress
            - finalizing
            - completed
            - failed
            - expired
            - cancelling
            - cancelled
          description: >-
            Lifecycle state. `completed`, `failed`, `expired`, and `cancelled`
            are terminal. `expired` and `cancelled` batches still expose partial
            output.
          example: in_progress
        model:
          type: string
          description: >-
            The model the batch runs on, once validation has read it from the
            input file.
          example: morph-glm53flash
        output_file_id:
          type:
            - string
            - 'null'
          description: >-
            File holding one `BatchOutputLine` per request the model answered.
            Set once the batch is terminal; `null` before that and when nothing
            completed.
          example: null
        error_file_id:
          type:
            - string
            - 'null'
          description: >-
            File holding one `BatchErrorLine` per request that never got a model
            response. Set once the batch is terminal; `null` before that and
            when nothing failed.
          example: null
        in_progress_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when processing started. `null` until
            it happens.
          example: 1780000012
        finalizing_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when output files started being
            written. `null` until it happens.
          example: null
        completed_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when the batch completed. `null` until
            it happens.
          example: null
        failed_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when the batch failed. `null` until it
            happens.
          example: null
        expired_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when the batch expired. `null` until it
            happens.
          example: null
        expires_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when the completion window closes.
            `null` until it happens.
          example: 1780086400
        cancelling_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when cancellation was requested. `null`
            until it happens.
          example: null
        cancelled_at:
          type:
            - integer
            - 'null'
          description: >-
            Unix timestamp (seconds) for when cancellation finished. `null`
            until it happens.
          example: null
        request_counts:
          $ref: '#/components/schemas/BatchRequestCounts'
        errors:
          type:
            - object
            - 'null'
          properties:
            object:
              type: string
              description: Object type of the error list, always `list`.
              example: list
            data:
              type: array
              items:
                $ref: '#/components/schemas/BatchError'
              description: Each validation problem found in the input file.
              example:
                - code: invalid_json_line
                  message: line 7 is not valid JSON
                  param: null
                  line: 7
          required:
            - object
            - data
          description: Why the batch failed validation, or `null`.
          example: null
        usage:
          anyOf:
            - $ref: '#/components/schemas/BatchUsage'
            - type: 'null'
          description: Token totals so far, or `null` before any request has completed.
          example:
            input_tokens: 824
            input_tokens_details:
              cached_tokens: 0
            output_tokens: 36
            output_tokens_details:
              reasoning_tokens: 0
            total_tokens: 860
      required:
        - id
        - object
        - endpoint
        - input_file_id
        - completion_window
        - metadata
        - created_at
        - status
        - output_file_id
        - error_file_id
        - in_progress_at
        - finalizing_at
        - completed_at
        - failed_at
        - expired_at
        - expires_at
        - cancelling_at
        - cancelled_at
        - request_counts
        - errors
        - usage
      description: A batch and where it is in its lifecycle.
      example:
        id: batch_5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c
        object: batch
        endpoint: /v1/chat/completions
        input_file_id: file_9c2c1c3e-5b6a-4f0e-8d0f-2a1b3c4d5e6f
        completion_window: 24h
        metadata:
          job: nightly-summaries
        created_at: 1780000000
        status: in_progress
        model: morph-glm53flash
        output_file_id: null
        error_file_id: null
        in_progress_at: 1780000012
        finalizing_at: null
        completed_at: null
        failed_at: null
        expired_at: null
        expires_at: 1780086400
        cancelling_at: null
        cancelled_at: null
        request_counts:
          total: 2
          completed: 1
          failed: 0
        errors: null
        usage:
          input_tokens: 824
          input_tokens_details:
            cached_tokens: 0
          output_tokens: 36
          output_tokens_details:
            reasoning_tokens: 0
          total_tokens: 860
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_request_error
              description: Machine-readable error code.
            message:
              type: string
              example: The request body is missing the `model` field.
              description: Human-readable explanation of the failure.
          required:
            - code
            - message
      required:
        - error
      description: Standard error envelope returned by every non-2xx response.
      example:
        error:
          code: invalid_request_error
          message: The request body is missing the `model` field.
    BatchRequestCounts:
      type: object
      properties:
        total:
          type: integer
          description: Lines in the input file.
          example: 2
        completed:
          type: integer
          description: Requests the model answered with a 2xx.
          example: 1
        failed:
          type: integer
          description: >-
            Requests that got a non-2xx from the model or were written to the
            error file.
          example: 0
      required:
        - total
        - completed
        - failed
      description: >-
        Progress counters. Advance while the batch is `in_progress`; final once
        it is terminal.
      example:
        total: 2
        completed: 1
        failed: 0
    BatchError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable reason validation failed.
          example: invalid_json_line
        message:
          type: string
          description: What was wrong.
          example: line 7 is not valid JSON
        param:
          type:
            - string
            - 'null'
          description: The offending field, when there is one.
          example: null
        line:
          type:
            - integer
            - 'null'
          description: >-
            One-based line number in the input file, when the error is tied to a
            line.
          example: 7
      required:
        - code
        - message
        - param
        - line
      description: A batch-level validation error.
      example:
        code: invalid_json_line
        message: line 7 is not valid JSON
        param: null
        line: 7
    BatchUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          description: Prompt tokens across every completed request.
          example: 824
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
              description: Prompt tokens served from the prefix cache.
              example: 0
          required:
            - cached_tokens
          description: Breakdown of `input_tokens`.
          example:
            cached_tokens: 0
        output_tokens:
          type: integer
          description: Completion tokens across every completed request.
          example: 36
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
              description: Completion tokens spent on reasoning.
              example: 0
          required:
            - reasoning_tokens
          description: Breakdown of `output_tokens`.
          example:
            reasoning_tokens: 0
        total_tokens:
          type: integer
          description: Sum of input and output tokens.
          example: 860
      required:
        - input_tokens
        - input_tokens_details
        - output_tokens
        - output_tokens_details
        - total_tokens
      description: Token totals for the batch so far.
      example:
        input_tokens: 824
        input_tokens_details:
          cached_tokens: 0
        output_tokens: 36
        output_tokens_details:
          reasoning_tokens: 0
        total_tokens: 860
  responses:
    BadRequest:
      description: Malformed request — missing or invalid fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request_error
              message: The request body is missing the `model` field.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid API key provided.
    RateLimited:
      description: Rate limited — retry after the interval in the Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests. Retry in 12 seconds.
    InternalError:
      description: Internal error — safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internal_error
              message: Something went wrong on our side.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: >-
        Morph API key, passed as `Authorization: Bearer sk-...`. Create keys at
        https://www.morphllm.com/dashboard/api-keys.

````