Poll job status, progress, and (once completed) the transcript

curl --request GET \
  --url https://api.audivo.dev/v1/transcripts/{job_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.audivo.dev/v1/transcripts/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.audivo.dev/v1/transcripts/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.audivo.dev/v1/transcripts/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.audivo.dev/v1/transcripts/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "job_id": "job_7bQ2vXpL9mZaK4tR",
  "status": "failed",
  "episode_id": "ep_unzqwwyevfss5jtb",
  "show_title": "The Vergecast",
  "episode_title": "The week in gadgets",
  "estimated_credits": 180,
  "reserved_credits": 225,
  "released_credits": 225,
  "reservation_released": true,
  "ledger_event_ids": [
    "ledger_reserve_8f3a9c2b",
    "ledger_release_1d4e9f2c"
  ],
  "error": {
    "type": "unavailable",
    "code": "processing_failed",
    "message": "The worker exited unexpectedly while processing this job. The reservation was released.",
    "doc_url": "https://docs.audivo.dev/errors#processing_failed",
    "request_id": "req_8f3a9c2b1d4e",
    "retryable": true
  },
  "created_at": "2026-08-20T09:00:00Z",
  "started_at": "2026-08-20T09:00:04Z",
  "completed_at": "2026-08-20T09:14:22Z"
}

Transcripts

Poll job status, progress, and (once completed) the transcript

Polls a job. Unlike the synchronous create and episode-read operations, format has no default here — omitting it and passing ?format=json are different requests. Without ?format= the response is application/json status only: the job status object, and artifact is never present, regardless of status. ?format=json must be given explicitly to also receive the transcript: the same status object, now carrying artifact once status is completed — artifact is never implied by completed alone, so a caller polling for state does not repeatedly ship a whole transcript (see JobStatus).

Delivery format. format: text|srt|vtt|md on a completed job returns the raw artifact under its own media type (text/plain, application/x-subrip, text/vtt, text/markdown) rather than a JSON envelope, with provenance carried in headers — X-Transcript-Episode-Id, X-Transcript-Source, and X-Transcript-Timing-Precision — so every delivery format carries the same provenance. The single content-type switch: a payload over the ~5 MB inline limit returns 200 application/json with { transcript_url, expires_at } in every format, including the raw ones.

A non-json format against a job that is not completed is 409 job_not_completed — there is no artifact to render yet, and the answer is to keep polling with no format (or with format=json) until the job is terminal. It is not a reason to wrap the status object in a different media type.

GET

transcripts

{job_id}

Poll job status, progress, and (once completed) the transcript

curl --request GET \
  --url https://api.audivo.dev/v1/transcripts/{job_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.audivo.dev/v1/transcripts/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.audivo.dev/v1/transcripts/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.audivo.dev/v1/transcripts/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.audivo.dev/v1/transcripts/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "job_id": "job_7bQ2vXpL9mZaK4tR",
  "status": "failed",
  "episode_id": "ep_unzqwwyevfss5jtb",
  "show_title": "The Vergecast",
  "episode_title": "The week in gadgets",
  "estimated_credits": 180,
  "reserved_credits": 225,
  "released_credits": 225,
  "reservation_released": true,
  "ledger_event_ids": [
    "ledger_reserve_8f3a9c2b",
    "ledger_release_1d4e9f2c"
  ],
  "error": {
    "type": "unavailable",
    "code": "processing_failed",
    "message": "The worker exited unexpectedly while processing this job. The reservation was released.",
    "doc_url": "https://docs.audivo.dev/errors#processing_failed",
    "request_id": "req_8f3a9c2b1d4e",
    "retryable": true
  },
  "created_at": "2026-08-20T09:00:00Z",
  "started_at": "2026-08-20T09:00:04Z",
  "completed_at": "2026-08-20T09:14:22Z"
}

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: json → application/json, text → text/plain, srt → application/x-subrip, vtt → text/vtt, md → text/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.

Option 1
Option 2

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}$

show_title

string | null

required

The show's title as it was when this job or read was created (ADR-0036), or null when it was created without one: before 0.14.0, or from a feed that names no show. For an upload it is Uploads. Copied once, never updated.

Required string length: 1 - 300

episode_title

string | null

required

The episode's title as it was when this job or read was created, or null when it was created without one. For an upload it is the title given when the file was announced. Where a feed gave no title, a catalog read (GET /v1/episodes/{episode_id}/transcript) answers the identifier the catalog stores in its place.

Required string length: 1 - 300

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

Required range: 0 <= x <= 9007199254740991

created_at

string<date-time>

required

progress

object

Show child attributes

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.

Show child attributes

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.

Option 1
Option 2

Show child attributes

started_at

string<date-time>

completed_at

string<date-time>

Transcripts

Catalog

Quotes

Uploads

Groups

Account

Session

API Keys

Connected Apps

Billing

Data

Poll job status, progress, and (once completed) the transcript

Authorizations

Path Parameters

Query Parameters

Response