> ## 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 a podcast > Ask us to index a show that isn't in the catalog: send its Apple Podcasts, Spotify, YouTube or RSS link, and we screen it within minutes, then add it, reject it, or hand it to our team. When [lookup](/podcasts/lookup.md) or [search](/podcasts/search.md) can't find a show, you can ask us to index it. Send its link, and automatic screening decides most English-language shows within a minute or two: it adds the show to the catalog, or rejects it when it's content we don't index. Shows that screening can't decide go to our team. Requests are free. You can answer questions like: * "Can you start tracking this show? Here's its Apple Podcasts link." * "Did my request go through, and when can I query the show's episodes?" * "Why wasn't this show added?" ## Request a show Send the show's Apple Podcasts, Spotify or YouTube page, a `spotify:show:` URI, or its RSS feed URL. An Apple Podcasts episode link works too; it names its show. ```bash curl theme={"dark"} curl -X POST "https://api.particle.pro/v1/podcasts/requests" \ -H "X-API-Key: $PARTICLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://podcasts.apple.com/us/podcast/the-museum-files-podcast/id1534449931"}' ``` ```js JavaScript theme={"dark"} const res = await fetch("https://api.particle.pro/v1/podcasts/requests", { method: "POST", headers: { "X-API-Key": process.env.PARTICLE_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://podcasts.apple.com/us/podcast/the-museum-files-podcast/id1534449931", }), }); const request = await res.json(); ``` ```python Python theme={"dark"} res = httpx.post( "https://api.particle.pro/v1/podcasts/requests", json={"url": "https://podcasts.apple.com/us/podcast/the-museum-files-podcast/id1534449931"}, headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) request = res.json() ``` ```jsonc Response (202) theme={"dark"} { "id": "4qH2mVnT8cXbKpL3sWd9eR", "url": "https://podcasts.apple.com/us/podcast/the-museum-files-podcast/id1534449931", "platform": "apple", "platform_id": "1534449931", "title": "The Museum Files Podcast", "state": "requested", "requested_at": "2026-10-19T17:02:11Z" } ``` The status code tells you what happened: | Status | Meaning | | - | - | | `202` | A new request. Poll it for the outcome. | | `200` | Nothing new to request: you asked for this show before (your existing request comes back), or we already index it (`state` is `indexed`, `podcast` names the show, and there is no `id`). | | `422` | The value isn't a link to a show: a bare ID, a social profile, or a Spotify or YouTube episode. | | `429` | Your organization reached its daily limit (below). | Asking again for a show you already requested returns your existing request, so a retry is safe without an `Idempotency-Key`. Organizations that ask for the same show share one request. ## Follow a request Poll the request until `state` leaves `requested`. Screening usually decides within a minute or two. ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/requests/4qH2mVnT8cXbKpL3sWd9eR" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```jsonc Response theme={"dark"} { "id": "4qH2mVnT8cXbKpL3sWd9eR", "url": "https://podcasts.apple.com/us/podcast/the-museum-files-podcast/id1534449931", "platform": "apple", "platform_id": "1534449931", "title": "The Museum Files Podcast", "state": "indexed", "podcast": { "id": "Hk3mQ8vTn2cXbKpL9sWd4e", "slug": "the-museum-files-podcast", "title": "The Museum Files Podcast" }, "requested_at": "2026-10-19T17:02:11Z", "indexed_at": "2026-10-19T17:03:02Z" } ``` `state` is one of: | State | Meaning | | - | - | | `requested` | Waiting for automatic screening. | | `indexed` | The show is in the catalog, and `podcast` names it. Its slug works with every podcast endpoint. Episodes from the last two weeks arrive over the following hours, and new episodes as they're published. Older episodes are its [back catalogue](/podcasts/episodes.md#transcript-status-and-the-back-catalogue), which you can [have transcribed](/podcasts/transcription.md). | | `in_review` | Screening couldn't decide, and our team will add or reject the show. `reason` says why. | | `rejected` | We won't index the show. `reason` says why. | `reason` is a stable code and `detail` says it in a sentence. | Reason | State | Meaning | | - | - | - | | `no_feed` | `in_review` | A Spotify or YouTube link names no RSS feed, so our team finds it. | | `not_english` | `in_review` | Automatic screening covers English-language shows. | | `not_found_in_podcast_index` | `in_review` | We couldn't find the show's feed automatically. | | `dead_feed` | `in_review` | The feed no longer publishes. | | `previously_removed` | `in_review` | We removed the show before, for a reason other than its content. | | `ai_generated_suspected` | `in_review` | The show may be machine-generated. | | `screening_failed` | `in_review` | Screening couldn't finish. | | `radio_rebroadcast` | `in_review` | The show appears to be a radio or TV station's on-air programming re-uploaded. | | `content_type_uncertain` | `in_review` | The show may be content we don't index, but screening wasn't sure. | | `audiobook`, `guided_audio`, `non_speech_ambient`, `subliminal`, `language_instruction`, `kids_story`, `sermon_worship` | `rejected` | Readings of books, guided meditation or sleep audio, ambient sound or music, frequency tracks, language lessons, children's story time, or church services and sermons. | | `ai_generated`, `content_farm`, `low_value_publisher`, `syndication_spam`, `brand_impersonation` | `rejected` | Machine-generated shows, mass-produced feeds, and feeds that copy or imitate other shows. | | `removed` | `rejected` | The show was added, then removed from the catalog. | A show that's added keeps being screened as its episodes arrive, like every show in the catalog. If a later screen removes it, its request becomes `rejected` with that screen's reason. ## List your requests `GET /v1/podcasts/requests` lists your organization's requests, newest first. Filter with `state`, and set `limit` (default 25, at most 100). When `has_more` is true, pass the response's `cursor` to get the next page. ```bash curl theme={"dark"} curl -G "https://api.particle.pro/v1/podcasts/requests" \ -H "X-API-Key: $PARTICLE_API_KEY" \ --data-urlencode "state=in_review" ``` An empty `data` array means your organization has no requests in that state. It isn't an error. ## Daily limit Each organization can request 50 new shows in any 24 hours. Asking again for a show you already requested doesn't count. Past the limit, the request returns `429` with error code [`rate_limit_exceeded`](/errors/rate_limit_exceeded), a `Retry-After` header in seconds, and a `detail` that says when you can request more. Requests you already made carry on. ## Looking for something else? * **Is the show already indexed?** [Look it up](/podcasts/lookup.md) by its Apple, Spotify or YouTube ID or its feed URL first; a request for a show we index returns it straight away, too. * **Need one episode transcribed now?** See [transcription](/podcasts/transcription.md). ## Related * [Lookup by external identifier](/podcasts/lookup.md) * [Podcast overview](/podcasts/overview.md) * [Handling errors](/recipes/handle-errors.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.