Batch API

Submit complete long-form recordings, then poll a transcription job to a terminal state.

Choose Batch when the entire recording already exists and the workload is long-form: meetings, podcasts, interviews, calls, or archives. Upload the file once, persist the returned job ID, and retrieve the result asynchronously.

Direct HTTP V2 and SDK 0.18.0

For a new direct HTTP integration, prefer GET /v1/transcribe/{job_id} and its V2 response. The JavaScript and Python SDKs at 0.18.0 currently poll the legacy V1 route, so keep that response shape when you use the released SDK helpers.

Job lifecycle

Submit one complete audio file and record the returned jobId before doing other work.
Before polling, set save_result=true when a lost terminal response must be retrievable again; then use a bounded interval, an overall deadline, and jitter where workers share capacity.
Continue while the status is queued or processing.
Stop on every terminal status: consume done, surface failed, and treat cleared as unavailable output.

Endpoints

POST · Submit a transcription job

Upload audio, choose language and processing options, and receive a job ID.

GET · Get a job (V2)

Recommended direct HTTP lookup with the standard success wrapper.

GET · Get a job (V1 legacy)

Legacy response used by the JavaScript and Python SDK 0.18.0 helpers.

Handle every terminal state

Status	Meaning	Client action
`queued`	Waiting for processing	Keep polling within your deadline
`processing`	Transcription is running	Keep polling within your deadline
`done`	Output is ready	Validate and store the result you need
`failed`	Processing failed	Stop polling and surface the failure
`cleared`	Stored output was cleared	Stop polling; do not wait for a later result

Production notes

A submit can return 429 with remaining audio capacity in seconds. Back off and bound retries instead of immediately resubmitting.
A timeout after upload is ambiguous: the service may have accepted the file even when the client did not receive the response. Track attempts and reconcile before retrying.
Set both a per-request timeout and an overall polling deadline. Neither the API nor a helper loop should be allowed to wait forever.
The default save_result=false can clear stored fields after constructing a done or failed response. Use true for repeatable delivery, but do not infer a retention duration.
Use Fast for one bounded conversational utterance that is already complete. Keep long recordings on Batch.

Next steps

Batch REST guide

Build the complete direct HTTP lifecycle.

Transcribe a recording

Run a tested SDK 0.18.0 example.

Errors and rate limits

Make polling and retries safe.