Skip to main content
GET
Poll job status, progress, and (once completed) the transcript

Authorizations

Authorization
string
header
required

Authorization: Bearer hk_live_... for live keys or Authorization: Bearer hk_test_... for test-mode keys. hk_test_ keys resolve real public catalog metadata but return deterministic committed fixtures, never call inference, and never mutate live credits. This is the only transport for the credential: the x-api-key alias once documented was removed in 0.2.0, because the edge authorizer reads Authorization as its single identity source and a request on any other header is refused before it is authenticated.

Never accepted on a dashboardJwt operation, and there are no exceptions. GET /v1/usage and GET /v1/limits briefly declared both schemes (0.8.0); that was withdrawn in 0.8.1 because no deployed route could honor it — both operations are served by the control-plane API, whose authorizer verifies a Cognito token and refuses an hk_live_ credential on shape, and the customer API does not route either path. An API-key holder reads its balance and reservation from QuoteResponse, which carries balance_credits and reserved_credits on every quote. Every operation in this document takes one scheme or the other and refuses the wrong one as unauthenticated.

Path Parameters

job_id
string
required

Opaque, server-generated job identifier.

Maximum string length: 40
Pattern: ^job_[A-Za-z0-9]{16,32}$

Query Parameters

format
enum<string>

The derived output to return from GET /v1/transcripts/{job_id}. No default — deliberately not FormatQueryParam, which defaults to json on the operations where delivering content is the whole point of the call. Polling is different: the status-only option exists precisely so a caller can ask for state without shipping the transcript, and a default would make omitting format and passing format=json the same request, erasing that option. So: omit format entirely for status only — application/json, the job status object, artifact never present, whatever status is. Pass format=json explicitly to also receive the transcript once status is completed — the same status object, now with artifact. Pass format=text|srt|vtt|md to receive the raw artifact under its own media type (text/plain, application/x-subrip, text/vtt, text/markdown) once completed; against a job that has not reached completed, any non-status format is 409 job_not_completed.

Delivery-only: never affects the cache key or the produced transcript content. Delivery-only: never affects the cache key or the produced transcript content. Every format is derived at read time from the one canonical transcript. Response media type per format: jsonapplication/json, texttext/plain, srtapplication/x-subrip, vtttext/vtt, mdtext/markdown. The one exception is an oversized payload, which is application/json in every format (see TranscriptUrlRef).

Available options:
json,
text,
srt,
vtt,
md

Response

Job status — status only when format is omitted, artifact included when status is completed and format=json was explicitly requested — or the completed raw artifact (format=text|srt|vtt|md), or, for an oversized payload in any format, the transcript_url reference.

Failure/cancellation objects report reservation_released: true and never imply a cash refund occurred — a cash refund is a separate, explicit Stripe refund via POST /v1/billing/refund.

job_id
string
required

Opaque, server-generated job identifier.

Maximum string length: 40
Pattern: ^job_[A-Za-z0-9]{16,32}$
status
enum<string>
required

Legal transitions: validating → queued|failed|cancelled; queued → downloading|failed|cancelled; downloading → transcribing|failed; transcribing → merging|failed; merging → completed|failed. Terminal states (completed, failed, cancelled) have no further transitions. Cancellation is legal only from validating/queued; every non-terminal state may fail.

Available options:
validating,
queued,
downloading,
transcribing,
merging,
completed,
failed,
cancelled
episode_id
string
required

Canonical episode identifier.

Pattern: ^ep_[a-z2-7]{16}$
estimated_credits
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
reserved_credits
integer
required

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
created_at
string<date-time>
required
progress
object
settled_credits
integer

Present on terminal completed jobs; measured usage capped at the reservation.

Required range: 0 <= x <= 9007199254740991
released_credits
integer

Present on terminal states; the unused portion of the reservation released back to the account.

Required range: 0 <= x <= 9007199254740991
reservation_released
boolean

Present on terminal failed/cancelled jobs. Never implies a cash refund.

ledger_event_ids
string[]

Immutable ledger event IDs, present on terminal states.

Maximum array length: 20
Required string length: 1 - 80
error
object

Present when status is failed; code processing_failed with retryability metadata.

artifact
object

The completed transcript, in JSON delivery. Present only when status is completed and the caller explicitly asked for it with ?format=json on GET /v1/transcripts/{job_id}PollFormatQueryParam has no default, so omitting format there is a real, distinct request that never carries artifact, whatever status is. It is deliberately not required by completed: a client polling a finished job would otherwise be forced to re-download the whole transcript on every call, with no status-only option.

started_at
string<date-time>
completed_at
string<date-time>