Request a podcast

When lookup or search 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.

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"}'

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();

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()

Response (202)

{
  "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.

curl "https://api.particle.pro/v1/podcasts/requests/4qH2mVnT8cXbKpL3sWd9eR" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response

{
  "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, which you can have transcribed.
`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.

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, 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 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.

Getting started

Recipes

Podcasts

People

Companies

Knowledge graph

Alerts

Account

Errors

Request a show

Follow a request

List your requests

Daily limit

Looking for something else?

​Request a show

​Follow a request

​List your requests

​Daily limit

​Looking for something else?

​Related

Request a show

Follow a request

List your requests

Daily limit

Looking for something else?

Related