---
title: "List batches"
method: GET
path: "/api/v1/batches"
tags: ["OpenAI Batch"]
---

# List batches

`GET /api/v1/batches`

## Request

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

List batches from the selected provider using customer-owned credentials. The response is relayed in the provider's OpenAI-compatible shape.

## Query parameters

- `provider_id` string, required
- `after` string
- `limit` integer

## Response `200`

OpenAI-compatible batch list.

- object
  - `object` 'list', required
  - `data` object[], required
    - `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
  - `first_id` string, nullable
  - `last_id` string, nullable
  - `has_more` boolean

## Other responses

- `400`: `provider_id` is missing.
- `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.
- `424`: The upstream provider failed.

## Changes

- **2026-10-21** `c30bcb383ee8`: 13 breaking, 4 info
  - the response property `data/items/cancelled_at` became nullable for the status `200`
  - the response property `data/items/cancelling_at` became nullable for the status `200`
  - the response property `data/items/completed_at` became nullable for the status `200`
  - the response property `data/items/error_file_id` became nullable for the status `200`
  - …13 more
- **2026-10-02** `b830b79cfd52`: 3 info
  - added the non-success response with the status `403`
  - the response property `detail` became required for the status `400`
  - the response property `detail` became required for the status `401`
- **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 `api-v-1-batches-retrieve` removed and replaced with `openAiBatch_api_v1_batches_retrieve`
- **2026-08-22** `b18c72975097`: 1 warning
  - for the `query` request parameter `limit`, the min was set to `1.00`

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

---

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