---
title: "Create a batch"
method: POST
path: "/api/v1/batches"
tags: ["OpenAI Batch"]
---

# Create a batch

`POST /api/v1/batches`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/v1/batches`
- Auth: HTTP bearer

Create an OpenAI-compatible batch processing job from an uploaded JSONL file. `provider_id` is required and selects the customer-owned provider credential used for the batch.

## Headers

- `X-Data-Respan-Params` string

## Request body

- object
  - `input_file_id` string, required: Uploaded JSONL file ID.
  - `endpoint` '/v1/chat/completions' | '/v1/embeddings', required: Endpoint each JSONL request targets.
  - `completion_window` '24h', required
  - `metadata` object: Custom metadata for tracking.
  - `customer_identifier` string: End-user identifier for logging.
  - `custom_identifier` string: Custom identifier for querying.
  - `thread_identifier` string: Conversation thread identifier.
  - `environment` string: Environment tag.
  - `provider_id` string, required: Provider route with customer-owned credentials.

## Response `200`

Created batch.

- object
  - `id` string, required: Batch ID.
  - `object` string
  - `endpoint` string
  - `input_file_id` string
  - `output_file_id` string, nullable: Output file ID, available when the batch completes.
  - `error_file_id` string, nullable: Error file ID, when provider errors are available.
  - `completion_window` string
  - `status` 'validating' | 'pending' | 'in_progress' | 'finalizing' | 'completed' | 'failed' | 'expired' | 'cancelling' | 'cancelled', required
  - `created_at` integer: Unix timestamp.
  - `in_progress_at` integer, nullable
  - `expires_at` integer, nullable
  - `finalizing_at` integer, nullable
  - `completed_at` integer, nullable
  - `failed_at` integer, nullable
  - `expired_at` integer, nullable
  - `cancelling_at` integer, nullable
  - `cancelled_at` integer, nullable
  - `request_counts` object
    - `total` integer
    - `completed` integer
    - `failed` integer
  - `metadata` object
  - `errors` unknown

## Other responses

- `400`: Bad Request
- `401`: You haven't added your own key for the provider in Settings › Providers, or the provider rejected it. Files and batches always run on your own key; Respan credits can't cover them.
- `403`: The API key is missing, invalid or expired.

## Changes

- **2026-10-21** `c30bcb383ee8`: 12 breaking, 4 info
  - request body became required
  - the response property `cancelled_at` became nullable for the status `200`
  - the response property `cancelling_at` became nullable for the status `200`
  - the response property `completed_at` became nullable for the status `200`
  - …12 more
- **2026-10-02** `b830b79cfd52`: 3 warning, 2 info
  - removed the optional property `error` from the response with the `401` status
  - removed the optional property `error_class` from the response with the `401` status
  - removed the optional property `id` from the response with the `401` status
  - added the non-success response with the status `403`
  - …1 more
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `create-batch` removed and replaced with `openAiBatch_createBatch`

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/v1/batches/post.md)

---

[API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)