curl -H "X-API-Key: $PARTICLE_API_KEY" \
"https://api.particle.pro/v1/podcasts/episodes/lookup?identifier=1000785846210%2Chttps%3A%2F%2Fopen.spotify.com%2Fepisode%2F4nREPHunYQprNJQiZeuJcy"{
"results": [
{
"identifier": "<string>",
"episode": {
"has_transcript": true,
"id": "<string>",
"title": "<string>",
"transcript_status": "transcribed",
"podcast": {
"id": "<string>",
"title": "<string>",
"best_rank": {
"captured_at": "2023-11-07T05:31:56Z",
"chart_type": "top_podcasts",
"rank": 123,
"source": "apple",
"category_slug": "<string>",
"country": "<string>"
},
"image_url": "<string>",
"popularity": 123,
"publisher": {
"id": "<string>",
"name": "<string>",
"slug": "<string>"
},
"slug": "<string>"
},
"published_at": "2023-11-07T05:31:56Z",
"slug": "<string>",
"web_url": "<string>"
}
}
]
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Look up episodes by external identifier
Resolves one or more external episode identifiers or links to Particle episodes. Paste a Spotify, Apple Podcasts or YouTube episode link as it is and it is resolved by the platform it points to; links from different platforms may share a call, and platform is then optional. Bare identifiers need platform: Apple Podcasts episode IDs (the ?i= value in an Apple Podcasts URL), Spotify episode IDs and YouTube video IDs; the episode’s RSS guid — the identifier the publisher’s own feed carries, and the one most podcast tooling keys on — and a podcastindex episode ID; and hosting-platform IDs read from the episode’s audio URL: megaphone, omny, acast and art19. Pass a comma-separated list (up to 100 per call). Guids and hosting-platform IDs are matched exactly as supplied and never read as links, since a guid is whatever string the feed carries and is often itself a URL. Because identifiers are comma-separated, a guid that itself contains a comma cannot be expressed here — about 1.2% of episodes, almost all of them SoundCloud-hosted, whose guids take the form tag:soundcloud,2010:tracks/123; look those episodes up by another identifier. Each result echoes the input identifier alongside the matched episode and its podcast; unresolved identifiers omit the episode field entirely so bulk callers can correlate inputs and outputs by key presence without doing a separate join. This is the episode-level counterpart to GET /v1/podcasts/lookup. Coverage is partial and differs by identifier, so a miss is not an error: Apple exposes only the most recent episodes of each show, so older back-catalogue episodes may not resolve; the first lookup of a Spotify episode can take a few seconds, and a call resolves at most 10 Spotify episodes not looked up before — retry the rest; YouTube resolves any video already discovered for an episode; guid is the broadest at roughly 89% of episodes; and a hosting-platform ID resolves only for episodes served by that host.
curl -H "X-API-Key: $PARTICLE_API_KEY" \
"https://api.particle.pro/v1/podcasts/episodes/lookup?identifier=1000785846210%2Chttps%3A%2F%2Fopen.spotify.com%2Fepisode%2F4nREPHunYQprNJQiZeuJcy"{
"results": [
{
"identifier": "<string>",
"episode": {
"has_transcript": true,
"id": "<string>",
"title": "<string>",
"transcript_status": "transcribed",
"podcast": {
"id": "<string>",
"title": "<string>",
"best_rank": {
"captured_at": "2023-11-07T05:31:56Z",
"chart_type": "top_podcasts",
"rank": 123,
"source": "apple",
"category_slug": "<string>",
"country": "<string>"
},
"image_url": "<string>",
"popularity": 123,
"publisher": {
"id": "<string>",
"name": "<string>",
"slug": "<string>"
},
"slug": "<string>"
},
"published_at": "2023-11-07T05:31:56Z",
"slug": "<string>",
"web_url": "<string>"
}
}
]
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Authorizations
Pass your API key in the X-API-Key header (recommended).
Query Parameters
What kind of identifier you are resolving. Optional when every identifier is a link: a Spotify, Apple Podcasts or YouTube episode URL, or a spotify:episode: URI, is always resolved by the platform it points to. Needed for bare identifiers: 'apple' (alias 'itunes') resolves Apple Podcasts episode IDs — the ?i= value in an Apple Podcasts URL. 'spotify' resolves Spotify episode IDs. 'youtube' resolves YouTube video IDs against the videos discovered for each episode. 'guid' resolves the episode's RSS guid, the identifier carried in the publisher's own feed and the one most podcast tooling keys on. 'podcastindex' resolves a PodcastIndex episode ID. 'megaphone', 'omny', 'acast' and 'art19' resolve a hosting platform's own episode ID, read from the episode's audio URL. Platform slugs must be ones reported on external-links responses; 'rss' is not accepted here because a feed URL identifies a show, not an episode.
"apple"
One or more episode identifiers or links to resolve. Pass a comma-separated list to look up many at once (max 100 per call); links from different platforms may be mixed. Spotify, Apple Podcasts and YouTube episode links are understood in their common forms (share links with a locale or ?si= token, embed URLs, youtu.be, /live/, /shorts/). guid, podcastindex and hosting-platform values are used exactly as given — a guid is whatever string the feed carries, which is often itself a URL, so it is never read as a link. The identifier is echoed back exactly as supplied, not normalized.
1 - 100 elements[
"1000785846210",
"https://open.spotify.com/episode/4nREPHunYQprNJQiZeuJcy"
]
Response
OK
One result per unique input identifier, in request order
Show child attributes
Show child attributes
Was this page helpful?