API Guides

Batch REST API

Submit a recording to the batch REST API, poll the job to a terminal status, and retry without creating duplicate jobs.

Batch is the direct HTTP route for long, complete recordings (choose a workflow): upload once, get a jobId, and poll until the job finishes. Send x-api-key from your backend; REST calls don't need an Origin header (Authentication). Size and duration limits are in Limits.

Submit a job

Upload one audio file in the file field of a multipart/form-data body. This request transcribes Arabic–English code-switched speech with speaker diarization:

curl -sS -X POST "$API_URL/v1/transcribe/codeswitch?diarization=1" \
  -H "x-api-key: $API_KEY" \
  -F "[email protected]"

A 200 means the job is queued, not finished (trimmed):

{ "jobId": "e5e90424-de35-4976-8951-04edae59fae8", "status": "queued" }

Store jobId with your own work item before you do anything else; it's the only handle to the job.

SelectorWhereValuesDefault
langPathen, ar, codeswitch, autoRequired
asrQueryAn ASR model keyThe language's configured model
diarizationQuery0, 1, d1, d2, d3Off; 1 selects the default level
itnQuery0, 1Off
redactQuery0, 1Off

true and false work wherever 1 and 0 do. For model keys and the differences between diarization levels, see Models. An unknown asr key returns 400 ASR_MODEL_NOT_FOUND.

Poll for the result

Set JOB_ID to the returned jobId and read the job with the V2 route:

curl -sS -X GET "$API_URL/v1/transcribe/$JOB_ID?save_result=true" \
  -H "x-api-key: $API_KEY"

Response (trimmed):

{
  "message": "success",
  "data": {
    "id": "e5e90424-de35-4976-8951-04edae59fae8",
    "language": "codeswitch",
    "audio_duration": 72.6085,
    "status": "done",
    "final_result": "Yeah, I mean, look, to start with, as you know, building infrastructure…",
    "final_word_segments": [{ "start_time": 0.08, "end_time": 0.36, "word": "Yeah," }],
    "diarization_segments": [{ "start_time": 0, "end_time": 14.56, "speaker": "SPEAKER_1" }]
  }
}

Keep polling while data.status is queued or processing. Stop on done, failed, or cleared (job statuses). Poll every 2 s, with a timeout on each request and an overall deadline.

Every job status returns HTTP 200. Retry a 5xx read (safe with save_result=true) and stop on 404 TRANSCRIPTION_JOB_NOT_FOUND. Other codes: Error codes.

RouteUseTranscriptWord timingsSpeakers
GET /v1/transcribe/{job_id} (V2)New direct integrationsdata.final_resultdata.final_word_segments (no speaker)data.diarization_segments
GET /v1/transcribe/{job_id}/{lang} (V1)Legacy; used by the SDKsresults.transcriptresults.offsets (word, startTime, endTime, speaker)diarization_segments

The two shapes use the same statuses but different field names and casing, so model each one with its own type. The V1 {lang} segment is required but ignored. Read result fields only when the status is done; final_result and final_word_segments already include ITN and redaction when you enable them. A failed response doesn't include a reason. A failed job is final; submitting the file again creates a new job.

Read the result again

Both result routes accept save_result, which defaults to false. With the default, a read that returns done or failed can clear the stored result, and later reads return cleared. Save the result in your own storage once you read done.

Pass save_result=true on every poll if you may need to read the result more than once, for example after a network error or from a second worker.

Force-aligned diarization

If you need a speaker on every word, poll the V1 route; it applies the rule below server-side and puts a speaker on each word in results.offsets. On V2, assign each word to the segment containing its start_time; otherwise use the nearest-boundary rule below.

The V1 query parameter diarization_force_align sets the label for a word whose startTime is outside every speaker segment:

diarization_force_alignSpeaker for that word
true (default)The speaker of the nearest segment boundary, measured from the word's midpoint; ties go to the earlier segment
falseUNKNOWN_SPEAKER

If the result has no speaker segments, speaker is null either way. The parameter changes only word labels; diarization_segments stays the same. The SDKs read the V1 route with the default, so SDK word offsets already carry speakers. Treat labels such as SPEAKER_1 as opaque strings that distinguish speakers within one result. They don't identify anyone.

Retries and duplicates

Submission has no idempotency key, and there's no endpoint to list or look up jobs. If you never saw the jobId, you can't recover it, so after an ambiguous upload you choose between accepting a possible duplicate job and not resubmitting.

Submission outcomeJob created?What to do
400, 401, 402, 403, 413, 422NoFix the request or account, then submit.
429, 503NoBack off and resubmit (retrying safely).
500, gateway 502 or 504, timeout, dropped connectionMaybeDon't resubmit automatically.

Record every jobId you receive, and record any submission whose outcome you didn't see. Result reads are safe to retry when every poll uses save_result=true.

Capacity responses

When your batch audio capacity is used up, submission returns 429 RATE_LIMIT_EXCEEDED with the remaining capacity in audio seconds (trimmed):

{ "code": "RATE_LIMIT_EXCEEDED", "retryable": true, "data": { "capacity": 120.5 } }

data.capacity isn't a wait time. A value of 0 can mean no balance was available. Use it to decide whether a recording fits, and queue larger work for later. A gateway rate limit can return 429 without this body; treat a missing data.capacity as plain backoff. 402 CREDITS_EXHAUSTED is different: the account is out of credit, and retrying won't help. For backoff rules, see Retrying safely.

Next steps

On this page