---
title: "Create Batch"
method: POST
path: "/v3/batches"
tags: ["Batches"]
---

# Create Batch

`POST /v3/batches`

## Request

- Base URL: `https://api.edenai.run`
- URL: `https://api.edenai.run/v3/batches`
- Auth: HTTP bearer

Create a chat batch.

Send the JSONL file as the `file` part of a multipart form, or upload it first with
POST /v3/upload with `purpose` set to `batch` and send its `file_id` as `input_file_id`
in a JSON body, the shape the
OpenAI SDK's `batches.create` sends. Both are validated the same way.

The batch runs on the model's provider, OpenAI, Anthropic, Mistral, Amazon Bedrock or
Vertex AI, within 24 hours at the
model's batch rates. Batch `metadata` is kept by Eden AI and sent to OpenAI and Mistral. Poll
GET /v3/batches/{batch_id} until `status` is `completed`, `failed`, `expired` or
`cancelled`, then read the results from GET /v3/batches/{batch_id}/results.

## Request body

- object: The JSON create body of OpenAI's batch API (``client.batches.create``), naming a file uploaded through ``POST /v3/upload`` in place of the multipart file part. Any other field is a 422 naming it, ``output_expires_after`` included: results are kept as long as OpenAI keeps them for every batch here (`jobs.results_promised_until`).
  - `input_file_id` string, uuid, required: The `file_id` `POST /v3/upload` returned for the JSONL file of requests.
  - `endpoint` string: The endpoint every line calls. Only `/v1/chat/completions` is accepted.
  - `completion_window` string: Only `24h` is accepted.
  - `metadata` object, nullable: Up to 14 string pairs attached to the batch, keys at most 64 characters and values at most 512. The keys `eden_batch_id` and `eden_request_id` are reserved.
  - `webhook_receiver` string, nullable: URL notified once the batch has finished and settled.

## Response `200`

Successful Response

- BatchObject: A chat batch.
  - `id` string, required: The batch id.
  - `object` 'batch': Always `batch`.
  - `endpoint` string: The endpoint every request of the batch calls.
  - `model` string, required: The model id every line of the batch named, as written: `openai/<model>`, `anthropic/<model>`, `mistral/<model>`, `amazon/<model>@eu` or `vertex/<model>@eu`, or an alias of it.
  - `status` 'validating' | 'in_progress' | 'finalizing' | 'completed' | 'failed' | 'expired' | 'cancelling' | 'cancelled', required: Where the batch is in its lifecycle.
  - `request_counts` BatchRequestCounts: How many of the batch's requests have finished, as the provider last reported them.
    - `total` integer: Requests in the batch.
    - `completed` integer: Requests that succeeded.
    - `failed` integer: Requests that failed.
  - `metadata` object, nullable: The key/value pairs given at create.
  - `created_at` integer, required: When the batch was created, Unix seconds.
  - `finished_at` integer, nullable: When the batch finished and settled, Unix seconds.
  - `cost` string, nullable: What the batch billed, in US dollars, once it finished; null before. Each request that succeeded bills its tokens at the model's batch rates; a failed one, or one that never ran, bills zero. A request that succeeded with no token count bills an estimate at the same rates: its prompt tokens, the output its response shows and a reasoning allowance, the output never above the most the request could produce. A request the provider counts as completed with no result line bills the same estimate with no output shown. When the results cannot be read, every request that may have run bills that estimate.
  - `error` string, nullable: Why the batch failed, when it did.
  - `results_available` boolean: Whether `GET /v3/batches/{batch_id}/results` is sure to serve this batch, read from the stored batch with no call to the provider: it has finished, was created at the provider, its recorded provider status is ended, and it was created less than 30 days ago, less one hour (29 days on Anthropic, which keeps results for 29 days: `jobs.results_promised_until`); past it this reads false, and the results route still tries and answers 410 once the results are gone. False while the batch runs, and for a batch that ended before the provider accepted it. A batch settled past its deadline before the provider ended it reads false, and the results route checks the provider live and can still serve it.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/edenai/apis/eden-ai-api-v3.md) - [All operations](https://skmtc.dev/edenai/apis/eden-ai-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/edenai/apis/eden-ai-api-v3/revisions/20ddfd49a3f4?raw)