--- title: "Create a batch" method: POST path: "/v1/batches" tags: ["batch"] --- # Create a batch `POST /v1/batches` Start processing an uploaded input file. The batch is returned in `validating`; poll it until `status` is terminal. Every line must target `/v1/chat/completions` and name the same model, `custom_id` must be unique within the file, and `stream: true` is rejected. Billed per completed request at half the model's synchronous rate, including requests that complete before a cancel or expiry. ## Request body - CreateBatchRequest — Start a batch over an uploaded input file. - `input_file_id` string, required — Id of a file uploaded with `purpose: batch`. - `endpoint` '/v1/chat/completions', required — Must be `/v1/chat/completions`; every input line must use the same `url`. - `completion_window` '24h', required — Must be `24h`. Requests not finished by then are expired, and the completed ones are still returned. - `metadata` object — Up to 16 string pairs to tag the batch. Keys up to 64 characters, values up to 512. - `output_expires_after` object — Expiry policy for the output and error files. Defaults to 30 days. - `anchor` 'created_at', required — Only `created_at` is supported. Anchored to when the output file is written, not when the batch is created. - `seconds` integer, required — Seconds after the anchor at which the output and error files are deleted, from 3600 (1 hour) to 2592000 (30 days). ## Response `200` The new batch, in `validating`. - 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. - `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/post.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)