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

# Transcription requests

> Have back-catalogue episodes transcribed on request, and follow each request until its transcript is ready.

A podcast's older episodes are its [back catalogue](/podcasts/episodes.md#transcript-status-and-the-back-catalogue): we list them with their feed metadata, but have not transcribed them. Request one, and we transcribe it. Once it is transcribed it keeps its ID, and every episode endpoint serves its transcript, speakers, entities, topics, segments, ads and clips, exactly as for any other episode.

Requests belong to your organization, so they need an organization's API key. They are not available through per-request payment ([x402](/x402.md)), which has no organization to hold them.

## Find episodes to request

Back-catalogue episodes read `transcript_status: requestable`. List a show's with `transcript_status=requestable`:

```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/crime-junkie/episodes?transcript_status=requestable&until=2020-01-01" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```bash CLI theme={"dark"}
particle podcast episodes crime-junkie --transcript-status requestable --until 2020-01-01
```

`GET /v1/podcasts/{id}?include=coverage` counts a show's episodes by `transcript_status` and by year, to plan requests without paging through them.

## Request a transcript

Send one episode per request:

```bash curl theme={"dark"}
curl -X POST "https://api.particle.pro/v1/podcasts/transcription/requests" \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"episode_id": "5HZ8M9tlTQ0yTgtObZ5zJs"}'
```

```bash CLI theme={"dark"}
particle transcription create 5HZ8M9tlTQ0yTgtObZ5zJs
```

A request that queues the episode answers `202` with the new request:

```json theme={"dark"}
{
  "id": "5zFTy7HD96FeUt9QPOXNXi",
  "episode_id": "5HZ8M9tlTQ0yTgtObZ5zJs",
  "podcast_id": "sOFDtTJovkWaaEhasy1E4",
  "state": "queued",
  "created_at": "2026-10-02T05:40:56.278899Z"
}
```

Only a `202` is billed as a transcription request, at your plan's price for `POST /v1/podcasts/transcription/requests`, and counts as 100 requests against your monthly request usage. Every other successful request answers `200` and is billed at the regular lookup price, because there is nothing new to transcribe:

| You requested | Response |
| - | - |
| An episode you requested before | Your existing request. |
| An episode another organization's request already queued | Your own request, which follows the same transcription. |
| An episode we already hold | No request is created: there is no `id`, and `state` says where its transcript stands. |

So requesting an episode again, or one somebody else is already paying to transcribe, never costs a second transcription.

You pay only for transcripts we deliver. A billed request that ends `failed` is refunded automatically, usually within half an hour: the included requests, prepaid credit or overage it used is returned to your organization, and the request's `refunded_at` says when. To retry a request that timed out without paying for the lookup either, send an [`Idempotency-Key`](/idempotency) and resend the same key: the retry gets the first response back and is not billed.

## How many, and how long

There is no limit on how many episodes you request. Send requests as fast as you like, within the API's general [rate limit](/concepts.md#rate-limits) of 10,000 calls a minute per organization.

Requests are transcribed concurrently, including episodes of the same podcast, so a batch of a few dozen takes about as long as its longest episode. A larger batch is worked through as earlier requests finish, with organizations served by plan and then evenly, so one organization's large backlog does not hold up anyone else's requests.

From the request to `state: transcribed` usually takes:

| Episode length | Usually transcribed within |
| - | - |
| Under 1 hour | 2 minutes |
| 1 to 2 hours | 3 minutes |
| Over 2 hours | 6 minutes |

`transcribed` means the transcript and its speakers are ready. The rest of the episode's data (segments, clips, entities, topics and ads) usually follows within a few minutes more.

## Follow a request

A request moves through these states:

| `state` | Meaning |
| - | - |
| `queued` | Waiting its turn. The episode reads `transcript_status: queued`. |
| `admitted` | Being transcribed (`admitted_at` is when it started). The episode reads `transcript_status: processing`. |
| `transcribed` | The transcript is available (`completed_at` is when). The episode reads `transcript_status: transcribed`. |
| `failed` | It will not be transcribed. `failure_reason` says why, for example `enclosure_gone` when the publisher has removed the audio, `podcast_removed` when the podcast has left the catalog, or `timed_out` when transcription did not finish in time. |

Follow a request with either of:

* `GET /v1/podcasts/transcription/requests/{id}`, the request itself;
* `GET /v1/podcasts/episodes/{id}`, whose `transcript_status` changes as the request does.

Checking every 15 to 30 seconds is plenty. Stop at `transcribed` or `failed`: both are final.

```json theme={"dark"}
{
  "id": "5zFTy7HD96FeUt9QPOXNXi",
  "episode_id": "5HZ8M9tlTQ0yTgtObZ5zJs",
  "podcast_id": "sOFDtTJovkWaaEhasy1E4",
  "state": "transcribed",
  "created_at": "2026-10-02T05:40:56.278899Z",
  "admitted_at": "2026-10-02T05:41:12.435531Z",
  "completed_at": "2026-10-02T05:43:17.079322Z"
}
```

`GET /v1/podcasts/transcription/requests` lists your organization's requests, newest first, filtered by `state` and `podcast_id`. To follow a batch, list it rather than polling each request: `?state=transcribed&podcast_id=…` returns the ones that have finished. Reading requests is never billed.

A back-catalogue episode does not appear in the [episode feed](/podcasts/feed.md) or [stream](/podcasts/stream.md) when it is transcribed: they carry the episodes podcasts publish, and an old episode transcribed today is not news. Follow your requests instead.

## Errors

| Status | Error code | When |
| - | - | - |
| `404` | `not_found` | No episode has that ID, or its podcast is no longer in the catalog. |
| `422` | [`episode_audio_unavailable`](/errors/episode_audio_unavailable) | The episode's feed entry has no playable audio, or the publisher's server says the audio no longer exists. |

None of these is billed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.