Retrieve a batch

GET

https://api.respan.ai/api/v1/batches/:batch_id

GET

/api/v1/batches/:batch_id

$ curl https://api.respan.ai/api/v1/batches/batch_abc123 \
>      -H "Authorization: Bearer <respanApiKey>" \
>      -H "Content-Type: application/json"

1 {
2   "id": "batch_abc123",
3   "status": "in_progress",
4   "object": "batch",
5   "endpoint": "/v1/chat/completions",
6   "input_file_id": "file-abc123",
7   "output_file_id": "file-output789",
8   "error_file_id": "file-error456",
9   "completion_window": "24h",
10   "created_at": 1710000000,
11   "in_progress_at": 1710003600,
12   "expires_at": 1710086400,
13   "finalizing_at": null,
14   "completed_at": null,
15   "failed_at": null,
16   "expired_at": null,
17   "cancelling_at": null,
18   "cancelled_at": null,
19   "request_counts": {
20     "total": 100,
21     "completed": 97,
22     "failed": 3
23   },
24   "metadata": {
25     "user_id": "user_789xyz",
26     "priority": "high",
27     "model": "gpt-4o-mini"
28   },
29   "errors": null
30 }

Retrieve an OpenAI-compatible batch job by ID.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

Path parameters

batch_idstringRequired

Batch ID.

Response

Batch details.

idstring

Batch ID.

statusenum

objectstring

endpointstring

input_file_idstring

output_file_idstring or null

Output file ID, available when the batch completes.

error_file_idstring or null

Error file ID, when provider errors are available.

completion_windowstring

created_atinteger

Unix timestamp.

in_progress_atinteger or null

expires_atinteger or null

finalizing_atinteger or null

completed_atinteger or null

failed_atinteger or null

expired_atinteger or null

cancelling_atinteger or null

cancelled_atinteger or null

request_countsobject

metadatamap from strings to any

errorsany or null

Provider error details, when available.

Errors

401

Unauthorized Error

404

Not Found Error

Authentication

Path parameters

Headers

Response

Errors