Batch API

Get transcription job status or result (V1 legacy)

Legacy compatibility operation used by JavaScript and Python SDK `0.18.0`.

GET/transcribe/{job_id}/{lang}

Legacy compatibility operation used by JavaScript and Python SDK 0.18.0. New direct HTTP integrations should use GET /transcribe/{job_id} (V2).

Use the jobId returned by submission. Poll status with a timeout on each request and one finite application deadline. Continue only for queued and processing; stop on done, failed, or cleared. Read results.transcript and results.offsets only for done. A failed V1 response does not include a machine-readable failure reason; cleared means stored result fields are unavailable. All five job statuses use HTTP 200; non-2xx responses are request, authentication, authorization, lookup, or server errors.

With the default save_result=false, a done or failed delivery can be single-consumption. Set save_result=true on every poll when a lost terminal response must be fetched again. The API defines no retention duration.

Authorization

ApiKeyAuth
x-api-key<token>

In: header

Path Parameters

job_id*string

Transcription job ID.

lang*string

Legacy compatibility segment required by the route. The current V1 handler does not use or validate this value. SDK 0.18.0 sends the language used at submission. New direct HTTP clients should use GET /transcribe/{job_id}.

Query Parameters

save_result?boolean

Leave stored terminal result fields available after this fetch. The default false can make a done or failed delivery single-consumption. Set true on every poll when terminal delivery must be retried. This option defines no retention duration.

diarization_force_align?boolean

Controls only results.offsets[].speaker; diarization_segments is unchanged. With true (default), a word whose startTime is outside every real segment uses the speaker from the nearest segment boundary, measured from the word midpoint; ties use the earlier segment. With false, such words use UNKNOWN_SPEAKER. With no real segments, speaker remains null. SDK 0.18.0 does not expose this option. Accepted values are true/false or 1/0.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -sS --fail-with-body --connect-timeout 10 --max-time 120 -X GET \  "https://example.com/transcribe/497f6eca-6276-4993-bfeb-53cbbbba6f08/en?save_result=true" \  -H "Origin: https://example.com"

Legacy transcription response

application/json

Job is queued

{
  "status": "queued",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": null
}

Job is processing

{
  "status": "processing",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": null
}

Job is complete

{
  "status": "done",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": "hello world",
    "offsets": [
      {
        "word": "hello",
        "startTime": 0,
        "endTime": 0.45,
        "speaker": "speaker-1"
      },
      {
        "word": "world",
        "startTime": 0.46,
        "endTime": 0.9,
        "speaker": null
      }
    ]
  },
  "diarization_segments": [
    {
      "start_time": 0,
      "end_time": 1,
      "speaker": "speaker-1"
    }
  ]
}

Job failed

{
  "status": "failed",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": null
}

Stored result fields are unavailable

{
  "status": "cleared",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": []
}

Invalid job ID, save_result, or diarization_force_align value

application/json

Invalid job ID

{
  "error": "error.uuid.invalid",
  "code": "VALIDATION_INVALID_UUID",
  "detail": "error.uuid.invalid",
  "job_id": "not-a-uuid",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Invalid save_result value

{
  "error": "error.api.error.param.save_result.invalid",
  "code": "VALIDATION_INVALID_PARAM",
  "detail": "error.api.error.param.save_result.invalid",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Invalid diarization_force_align value

{
  "error": "error.api.error.param.diarization_force_align.invalid",
  "code": "VALIDATION_INVALID_PARAM",
  "detail": "error.api.error.param.diarization_force_align.invalid",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Unauthorized

application/json

Example missing_key

{
  "error": "auth.unauthorized",
  "message": "unauthorized",
  "code": "AUTH_UNAUTHORIZED",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

The API key does not grant batch transcription access

application/json

Example scope_denied

{
  "error": "error.api_key.scope_denied",
  "code": "AUTH_FORBIDDEN",
  "detail": "scope not permitted",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Transcription job not found

application/json

Example missing_job

{
  "error": "error.transcription_job.get",
  "code": "TRANSCRIPTION_JOB_NOT_FOUND",
  "detail": "transcription job not found",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Legacy result lookup or post-response result clearing failed

application/json

Example lookup_failed

{
  "error": "error.transcription_job.get",
  "code": "SERVER_INTERNAL",
  "detail": "error.transcription_job.get",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

Example clear_failed

{
  "error": "error.transcription_job.clear_result_failed",
  "code": "SERVER_INTERNAL",
  "detail": "error.transcription_job.clear_result_failed",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

Invalid save_result value

{
  "error": "error.api.error.param.save_result.invalid",
  "code": "VALIDATION_INVALID_PARAM",
  "detail": "error.api.error.param.save_result.invalid",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Next steps

Keep V1 only where SDK 0.18.0 compatibility requires it. For a new direct HTTP client, move to V2; in either case, stop polling on done, failed, or cleared.

Move direct HTTP to V2

Use the recommended status and result contract for new HTTP integrations.

Use the released SDK safely

Follow the tested 0.18.0 recipe that still consumes the V1 shape.

Bound retries and polling

Separate terminal job states from transport and API failures.

Get transcription job status or result (V2)

Recommended status and result operation for new direct HTTP integrations.

Realtime HTTP API

HTTP streaming for bounded Fast input, live audio, diarization, and text-to-speech.

On this page

Next steps