---
title: "Request an episode's transcription"
method: POST
path: "/v1/podcasts/transcription/requests"
tags: ["Podcast Transcription", "tier:standard"]
---

# Request an episode's transcription

`POST /v1/podcasts/transcription/requests`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/podcasts/transcription/requests`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Queues an episode discovered in its podcast's back catalogue (transcript_status requestable) to be transcribed. Returns 202 with the new request that queues the episode, the only outcome billed as a transcription. Returns 200, billed as a lookup, when there is nothing to transcribe: you have requested the episode before (the existing request), another organization's request already queued it (your own request, tracking it), or we already hold the episode (no request is created, and state says where its transcript stands). There is no limit on how many episodes you request. Requests are transcribed concurrently, usually within a few minutes; a large batch is worked through as earlier requests finish, with organizations served by plan and then evenly. Poll GET /v1/podcasts/transcription/requests/{id} or the episode's transcript_status. The episode keeps its ID once transcribed, and every episode endpoint then serves it. 422 episode_audio_unavailable when its audio cannot be fetched. Send an Idempotency-Key to retry safely: a retry under the same key returns the first response and is not billed.

## Headers

- `Idempotency-Key` string

## Request body

- RequestTranscriptionRequestBody
  - `episode_id` string, required: The episode to transcribe: the id of an episode whose transcript_status is requestable, as GET /v1/podcasts/episodes?podcast_id=…&transcript_status=requestable lists them.

## Response `200`

Nothing to transcribe, billed as a lookup: an existing request, your own request joining another organization's queue, or an episode we already hold.

- TranscriptionRequest
  - `admitted_at` string, date-time: When transcription started.
  - `completed_at` string, date-time: When the request was transcribed or failed.
  - `created_at` string, date-time: When the request was made.
  - `episode` EpisodeCompactWithPodcast
    - `id` string, required: Episode ID
    - `podcast` PodcastCompact
      - `best_rank` PodcastRankingHandle
        - `captured_at` string, date-time, required
        - `category_slug` string
        - `chart_type` 'top_podcasts', required
        - `country` string
        - `rank` integer, required
        - `source` 'apple' | 'spotify', required
      - `id` string, required: Podcast ID
      - `image_url` string: Cover image URL
      - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints.
      - `publisher` PodcastPublisherCompact
        - `id` string, required: Publisher ID
        - `name` string, required: Publisher name
        - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs).
      - `slug` string: Human-readable slug identifier
      - `title` string, required: Podcast title
    - `published_at` string, date-time: Publication date
    - `slug` string: Human-readable slug identifier
    - `title` string, required: Episode title
    - `web_url` string: The episode's page on Radar, where it plays beside its transcript: https://radar.particle.pro/podcasts/{podcast}/episodes/{episode}, each segment the slug or, when there is none, the raw UUID. Append ?t={seconds} to start at a moment; the hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch the episode.
  - `episode_id` string, required: The episode, for GET /v1/podcasts/episodes/{id}. It keeps this ID once transcribed.
  - `failure_reason` string: Why a failed request will not be transcribed, e.g. enclosure_gone when the publisher removed the audio, or timed_out.
  - `id` string: The request's ID, for GET /v1/podcasts/transcription/requests/{id}. Absent when no request was needed because we already hold the episode: state then reports where its transcript stands.
  - `podcast` PodcastCompact
    - `best_rank` PodcastRankingHandle
      - `captured_at` string, date-time, required
      - `category_slug` string
      - `chart_type` 'top_podcasts', required
      - `country` string
      - `rank` integer, required
      - `source` 'apple' | 'spotify', required
    - `id` string, required: Podcast ID
    - `image_url` string: Cover image URL
    - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints.
    - `publisher` PodcastPublisherCompact
      - `id` string, required: Publisher ID
      - `name` string, required: Publisher name
      - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs).
    - `slug` string: Human-readable slug identifier
    - `title` string, required: Podcast title
  - `podcast_id` string: The episode's podcast.
  - `refunded_at` string, date-time: When a failed request's transcription charge was returned to your organization: the included request, prepaid credit or overage it drew. Absent until then, and on requests that were billed as a lookup.
  - `state` 'queued' | 'admitted' | 'transcribed' | 'failed', required: queued: waiting its turn. admitted: being transcribed. transcribed: the transcript is available. failed: it will not be transcribed; failure_reason says why.

## Other responses

- `202`: Accepted
- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)