> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audivo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit and poll

> The one-episode path: submit, follow the job, read the result.

The [Quickstart](/quickstart) prices a selection and confirms it as a group.
For a single episode there is a shorter path: `POST /v1/transcripts` names
one pointer and either returns the cached transcript at once, or accepts one
job in a group of one.

## Submit

```bash theme={null}
curl -X POST "$HARK_API/v1/transcripts" \
  -H "Authorization: Bearer hk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "feed_url": "'"$FEED_URL"'", "guid": "'"$GUID"'" }'
```

Exactly one of `url`, `feed_url` + `guid`, or `episode_id`. Optional fields:

| field           | meaning                                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `dry_run: true` | Price only. Returns `is_cached`, `estimated_credits`, `quote_ceiling_credits` and `quote_basis`; reserves nothing and creates nothing. |
| `language`      | A BCP-47 tag when you know the language. Omitted, the engine detects it. See [Languages](/languages).                                  |
| `format`        | Only `json` is served on this path; the other formats are read through the transcript endpoints below.                                 |

Three answers are possible:

* **200** with `is_cached: true` and the transcript inline: the episode was
  already transcribed. A cached read is charged, at the price on
  [Credits](/credits), and the response carries `X-Credits-Charged`.
* **202** with a `job_id`, its `group_id`, and the reservation: fresh work
  was accepted. The job holds `reserved_credits` until it settles.
* **200** with `dry_run: true`: the price, and nothing else.

## Idempotency

`Idempotency-Key` is any printable string up to 255 characters. Audivo keeps it
for **24 hours** with a hash of the body: the same key with the same body
returns the original answer, the same job and no second reservation; the same
key with a different body is refused as `idempotency_conflict`. Generate a
fresh key per intended submission and reuse it on every retry of that one.

## Poll

```bash theme={null}
curl "$HARK_API/v1/transcripts/$JOB_ID" \
  -H "Authorization: Bearer hk_live_..."
```

A job moves through these states, in this order, and never backwards:

```
validating → queued → downloading → transcribing → merging → completed
```

Any state can end in `failed`; `validating` and `queued` can end in
`cancelled`. While transcribing, `progress` reports `chunks_done`,
`chunks_total` and `percent`; chunks are fifteen-minute pieces of the audio
transcribed in parallel, so a long episode does not take proportionally
longer. `estimated_seconds` on the accepted job is a processing estimate for
choosing a poll interval, not audio length; every ten seconds is reasonable,
and a finished hour of audio is typically minutes away.

A terminal job reports what happened to the money: `settled_credits` and
`released_credits` on completion, `reservation_released: true` on failure or
cancellation. The sum is always the reservation.

## Read

Once `completed`, the same URL with `format` returns the transcript:

```bash theme={null}
curl "$HARK_API/v1/transcripts/$JOB_ID?format=json" -H "Authorization: Bearer hk_live_..."
curl "$HARK_API/v1/transcripts/$JOB_ID?format=srt"  -H "Authorization: Bearer hk_live_..."
```

Reading a job you paid for costs nothing, as often as you like. The shapes
and the size limit are on [Output formats](/formats).

## Cancel

There is no single-job cancel; jobs live in groups, and
`POST /v1/groups/{group_id}/cancel` cancels every member that has not
started, releasing each reservation exactly once. A job the worker has
already claimed runs to its end and settles normally.