---
title: "List batches"
method: GET
path: "/v1/batches"
tags: ["batch"]
---

# List batches

`GET /v1/batches`

Page through the key's batches, newest first.

## Query parameters

- `limit` integer — Batches per page. Default 20, max 100.
- `after` integer — Offset cursor: how many batches to skip. Add `limit` to it for each next page.

## Response `200`

The requested page of batches.

- BatchList — A page of batches.
  - `object` string, required — Object type of a batch page, always `list`.
  - `data` Batch[], required — Batches in this page.
    - `id` string, required — Batch identifier, `batch_` prefixed.
    - `object` string, required — Object type, always `batch`.
    - `endpoint` string, required — The endpoint every line targets. Always `/v1/chat/completions`.
    - `input_file_id` string, required — The file the batch reads its requests from.
    - `completion_window` string, required — Always `24h`. Requests still queued when the window closes are written to the error file as `batch_expired`.
    - `metadata` object, nullable, required — The key-value pairs you attached at creation, or `null`.
    - `created_at` integer, required — Unix timestamp (seconds) for when the batch was created.
    - `status` 'validating' | 'in_progress' | 'finalizing' | 'completed' | 'failed' | 'expired' | 'cancelling' | 'cancelled', required — Lifecycle state. `completed`, `failed`, `expired`, and `cancelled` are terminal. `expired` and `cancelled` batches still expose partial output.
    - `model` string — The model the batch runs on, once validation has read it from the input file.
    - `output_file_id` string, nullable, required — File holding one `BatchOutputLine` per request the model answered. Set once the batch is terminal; `null` before that and when nothing completed.
    - `error_file_id` string, nullable, required — 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.
    - `in_progress_at` integer, nullable, required — Unix timestamp (seconds) for when processing started. `null` until it happens.
    - `finalizing_at` integer, nullable, required — Unix timestamp (seconds) for when output files started being written. `null` until it happens.
    - `completed_at` integer, nullable, required — Unix timestamp (seconds) for when the batch completed. `null` until it happens.
    - `failed_at` integer, nullable, required — Unix timestamp (seconds) for when the batch failed. `null` until it happens.
    - `expired_at` integer, nullable, required — Unix timestamp (seconds) for when the batch expired. `null` until it happens.
    - `expires_at` integer, nullable, required — Unix timestamp (seconds) for when the completion window closes. `null` until it happens.
    - `cancelling_at` integer, nullable, required — Unix timestamp (seconds) for when cancellation was requested. `null` until it happens.
    - `cancelled_at` integer, nullable, required — Unix timestamp (seconds) for when cancellation finished. `null` until it happens.
    - `request_counts` BatchRequestCounts, required — Progress counters. Advance while the batch is `in_progress`; final once it is terminal.
      - `total` integer, required — Lines in the input file.
      - `completed` integer, required — Requests the model answered with a 2xx.
      - `failed` integer, required — Requests that got a non-2xx from the model or were written to the error file.
    - `errors` object, nullable, required — Why the batch failed validation, or `null`.
      - `object` string, required — Object type of the error list, always `list`.
      - `data` BatchError[], required — Each validation problem found in the input file.
        - `code` string, required — Machine-readable reason validation failed.
        - `message` string, required — What was wrong.
        - `param` string, nullable, required — The offending field, when there is one.
        - `line` integer, nullable, required — One-based line number in the input file, when the error is tied to a line.
    - `usage` BatchUsage, required — Token totals for the batch so far.
      - `input_tokens` integer, required — Prompt tokens across every completed request.
      - `input_tokens_details` object, required — Breakdown of `input_tokens`.
        - `cached_tokens` integer, required — Prompt tokens served from the prefix cache.
      - `output_tokens` integer, required — Completion tokens across every completed request.
      - `output_tokens_details` object, required — Breakdown of `output_tokens`.
        - `reasoning_tokens` integer, required — Completion tokens spent on reasoning.
      - `total_tokens` integer, required — Sum of input and output tokens.
  - `first_id` string, nullable, required — Id of the first batch in this page, or `null` when the page is empty.
  - `last_id` string, nullable, required — Id of the last batch in this page, or `null` when the page is empty.
  - `has_more` boolean, required — Whether more batches exist after this page.

## Other responses

- `400` — Malformed request — missing or invalid fields.
- `401` — Missing or invalid API key.
- `429` — Rate limited — retry after the interval in the Retry-After header.
- `500` — Internal error — safe to retry with backoff.

## Changes

- **2026-09-02** `681b2f463d11` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/morphllm/apis/morph-api/changes/v1/batches/get.md)

---

[API](https://skmtc.dev/morphllm/apis/morph-api.md) · [All operations](https://skmtc.dev/morphllm/apis/morph-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/morphllm/morph-api/revisions/681b2f463d11/schema)