---
title: "Retrieve a batch"
method: GET
path: "/v1/batches/{batch_id}"
tags: ["batch"]
---

# Retrieve a batch

`GET /v1/batches/{batch_id}`

Poll a batch. `request_counts` advances while it runs; once `status` is `completed`, `failed`, `expired`, or `cancelled`, download `output_file_id` and `error_file_id`. Poll every 30 to 60 seconds rather than holding a request open.

## Path parameters

- `batch_id` string, required — The `batch_` prefixed id returned when the batch was created.

## Response `200`

The batch.

- Batch — A batch and where it is in its lifecycle.
  - `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.

## Other responses

- `400` — Malformed request — missing or invalid fields.
- `401` — Missing or invalid API key.
- `404` — The requested resource does not exist.
- `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/:batch_id/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)