Jobs and batches
View as Markdown · Open in Claude Desktop
A tool call creates a job and returns 202 with the job. A job moves through queued, working and then one of completed, failed or cancelled.
Wait for the result
You have two choices.
- Poll.
GET /v1/jobs/<id>?wait=<seconds>holds the request open for up to 45 seconds and answers as soon as the job ends. Poll at most 1 request a second for each job. Status polls do not count against the per-minute limit. - Webhook. Register an endpoint and pass its
webhook_endpoint_idwhen you create the job. See webhooks.
Use GET /v1/jobs/<id>/events for a stream of progress events. DELETE /v1/jobs/<id> cancels a job and releases the time held for it.
Idempotency
Send an Idempotency-Key header on every POST that creates something. If your connection drops, send the same request with the same key and you get the original job back. The same key with a different body gets 409 IDEMPOTENCY_MISMATCH.
Batches
POST /v1/batches runs one tool over many inputs. A batch holds up to 20 files on Free, 100 on Plus and 500 on Pro. GET /v1/batches/<id> shows each item and an outputs list. POST /v1/batches/<id>/cancel stops the rest. A batch draws from your allowance like the same jobs run one by one.
Estimate before you run
POST /v1/estimate returns how much allowance a call would use and whether it is allowed, without starting a job.