> ## 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. # Request an episode's transcription > 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, which counts as 100 requests against your monthly request usage. 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. > [!TIP] > > Prefer the terminal? This endpoint is also a command in the Particle CLI: pick **Particle CLI** in the request example's language menu. [Install the Particle CLI](https://cli.particle.pro). ## OpenAPI ````yaml /openapi.json post /v1/podcasts/transcription/requests openapi: 3.1.0 info: contact: email: api@particle.pro name: Particle url: https://particle.pro description: >- Podcast API for transcripts, mentions and sponsorship data. 140,000+ podcasts transcribed, diarized and speaker-identified within minutes of airing, about 28,000 episodes a day. Search transcripts by keyword or meaning, track brand and company mentions with alerts, pull sponsor and ad-read data and rankings. REST API plus an MCP server for AI agents. Also company, people and topic intelligence. summary: >- Podcast API: transcripts, mentions, sponsors and rankings for 140,000+ podcasts. termsOfService: https://particle.pro/legal/tos-api title: Particle API version: 0.1.0 x-guidance: >- Podcast, people, company and topic intelligence. Authenticate with a pp_ API key (X-API-Key header) or pay per request with x402: a keyless call to a billable endpoint returns 402 with the payment requirements in the PAYMENT-REQUIRED header; sign the USDC transfer and repeat the request with PAYMENT-SIGNATURE. Start with GET /v1/podcasts/search?q=; the slugs in responses are the inputs to the other endpoints. Docs: https://docs.particle.pro; setup playbook: https://api.particle.pro/agents.md; endpoint and tool map with prices: https://api.particle.pro/llms.txt; credential recipe: https://api.particle.pro/auth.md. x-logo: url: https://particle.pro/favicon.svg servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] externalDocs: url: https://docs.particle.pro paths: /v1/podcasts/transcription/requests: post: tags: - Podcast Transcription - tier:standard summary: Request an episode's transcription description: >- 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, which counts as 100 requests against your monthly request usage. 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. operationId: request-podcast-episode-transcription parameters: - description: >- A key you choose, such as a UUID, to retry this request safely. Resend the same key with the same request and the first response is returned with `Idempotent-Replayed: true` instead of the request running again, for 24 hours after it succeeded. The same key with a different request returns 422 `idempotency_key_reused`; a retry while the first request is still running returns 409 `idempotency_key_in_use`. A request that fails does not use up its key. example: 4f9d1c2a-6b1e-4f7a-9d3c-2e8b5a7c1d40 in: header name: Idempotency-Key schema: maxLength: 128 minLength: 8 type: string requestBody: content: application/json: example: episode_id: 5HZ8M9tlTQ0yTgtObZ5zJs schema: $ref: '#/components/schemas/RequestTranscriptionRequestBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TranscriptionRequest' description: >- Nothing to transcribe, billed as a lookup: an existing request, your own request joining another organization's queue, or an episode we already hold. '202': content: application/json: schema: $ref: '#/components/schemas/TranscriptionRequest' description: Accepted default: content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: Error x-codeSamples: - label: cURL lang: curl source: |- curl -X POST \ -H "X-API-Key: $PARTICLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "episode_id": "5HZ8M9tlTQ0yTgtObZ5zJs" }' \ "https://api.particle.pro/v1/podcasts/transcription/requests" - label: Particle CLI lang: bash source: |- # Install: https://cli.particle.pro particle transcription create 5HZ8M9tlTQ0yTgtObZ5zJs components: schemas: RequestTranscriptionRequestBody: additionalProperties: false properties: episode_id: description: >- 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. type: string required: - episode_id type: object TranscriptionRequest: additionalProperties: false properties: admitted_at: description: When transcription started. format: date-time type: string completed_at: description: When the request was transcribed or failed. format: date-time type: string created_at: description: When the request was made. format: date-time type: string episode: $ref: '#/components/schemas/EpisodeCompactWithPodcast' description: >- The episode's id, title and publication date, so a list can be read without looking each one up. slug is set once the episode is transcribed or being transcribed, and absent if it was since removed. Its podcast is the podcast field beside it, not episode.podcast. episode_id: description: >- The episode, for GET /v1/podcasts/episodes/{id}. It keeps this ID once transcribed. type: string failure_reason: description: >- Why a failed request will not be transcribed, e.g. enclosure_gone when the publisher removed the audio, or timed_out. type: string id: description: >- 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. type: string podcast: $ref: '#/components/schemas/PodcastCompact' description: >- The episode's podcast, with its slug and title. Absent if the podcast was removed from the catalogue. podcast_id: description: The episode's podcast. type: string refunded_at: description: >- 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. format: date-time type: string state: description: >- queued: waiting its turn. admitted: being transcribed. transcribed: the transcript is available. failed: it will not be transcribed; failure_reason says why. enum: - queued - admitted - transcribed - failed type: string required: - episode_id - state type: object PlatformError: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string error_code: type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string resolve: $ref: '#/components/schemas/ErrorResolve' status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object EpisodeCompactWithPodcast: additionalProperties: false properties: id: description: Episode ID type: string podcast: $ref: '#/components/schemas/PodcastCompact' description: Parent podcast published_at: description: Publication date format: date-time type: string slug: description: Human-readable slug identifier type: string title: description: Episode title type: string web_url: description: >- 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. type: string required: - id - title type: object PodcastCompact: additionalProperties: false properties: best_rank: $ref: '#/components/schemas/PodcastRankingHandle' description: >- The single best (lowest-numbered) chart position this podcast currently holds across all charts. Omitted when the podcast holds no current chart appearances, and on endpoints that do not attach it. Reading a full chart (with country/category/source filters and history) remains premium; a single show's own placement is available on every plan. id: description: Podcast ID type: string image_url: description: Cover image URL type: string popularity: description: >- 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. format: double type: number publisher: $ref: '#/components/schemas/PodcastPublisherCompact' description: >- Publisher (network) attributed to this podcast. Present only when the embedding endpoint preloads publisher attribution and the podcast's publisher is known. slug: description: Human-readable slug identifier type: string title: description: Podcast title type: string required: - id - title type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ErrorResolve: additionalProperties: false properties: action: type: string endpoint: type: string message: type: string method: type: string url: type: string required: - message type: object PodcastRankingHandle: additionalProperties: false properties: captured_at: format: date-time type: string category_slug: type: string chart_type: enum: - top_podcasts type: string country: type: string rank: format: int64 type: integer source: enum: - apple - spotify type: string required: - source - chart_type - rank - captured_at type: object PodcastPublisherCompact: additionalProperties: false properties: id: description: Publisher ID type: string name: description: Publisher name type: string slug: description: >- 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). type: string required: - id - name type: object securitySchemes: ApiKeyHeader: description: Pass your API key in the X-API-Key header (recommended). in: header name: X-API-Key type: apiKey BearerAuth: description: Pass your API key as a Bearer token in the Authorization header. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.