> ## 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. # Look up episodes by external identifier > Resolves one or more external episode identifiers to Particle episodes. Eight kinds are accepted. Platform IDs: Apple Podcasts episode IDs (the `?i=` value in an Apple Podcasts URL) and YouTube video IDs. Feed and index 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. Hosting-platform IDs, read from the episode's audio URL: `megaphone`, `omny`, `acast` and `art19`. Pass `platform` once and a comma-separated list of identifiers (up to 100 per call). A full platform URL is accepted in place of a bare ID and the identifier is parsed out of it — an Apple Podcasts episode URL, or a YouTube watch, youtu.be, /live/, /shorts/ or /embed/ URL. Guids and hosting-platform IDs are matched exactly as supplied and never parsed, 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; 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. ## OpenAPI ````yaml /openapi.json get /v1/podcasts/episodes/lookup openapi: 3.1.0 info: description: Public API for Particle — news intelligence, financial data, and analysis. 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; agent onboarding recipe: https://api.particle.pro/auth.md. servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] paths: /v1/podcasts/episodes/lookup: get: tags: - Podcast Episodes - tier:standard summary: Look up episodes by external identifier description: >- Resolves one or more external episode identifiers to Particle episodes. Eight kinds are accepted. Platform IDs: Apple Podcasts episode IDs (the `?i=` value in an Apple Podcasts URL) and YouTube video IDs. Feed and index 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. Hosting-platform IDs, read from the episode's audio URL: `megaphone`, `omny`, `acast` and `art19`. Pass `platform` once and a comma-separated list of identifiers (up to 100 per call). A full platform URL is accepted in place of a bare ID and the identifier is parsed out of it — an Apple Podcasts episode URL, or a YouTube watch, youtu.be, /live/, /shorts/ or /embed/ URL. Guids and hosting-platform IDs are matched exactly as supplied and never parsed, 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; 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. operationId: lookup-episodes parameters: - description: >- What kind of identifier you are resolving. 'apple' (alias 'itunes') resolves Apple Podcasts episode IDs — the ?i= value in an Apple Podcasts URL. '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. explode: false in: query name: platform required: true schema: description: >- What kind of identifier you are resolving. 'apple' (alias 'itunes') resolves Apple Podcasts episode IDs — the ?i= value in an Apple Podcasts URL. '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. examples: - apple type: string - description: >- One or more episode identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). A full platform URL is accepted in place of a bare identifier and the ID is parsed out of it: for apple/itunes an Apple Podcasts episode URL (the ?i= value); for youtube a watch?v=, youtu.be/, /live/, /shorts/ or /embed/ URL. guid, podcastindex and hosting-platform values are used as given — a guid is whatever string the feed carries, which is often itself a URL, so it is never parsed. The identifier is echoed back exactly as supplied, not normalized. explode: false in: query name: identifier required: true schema: description: >- One or more episode identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). A full platform URL is accepted in place of a bare identifier and the ID is parsed out of it: for apple/itunes an Apple Podcasts episode URL (the ?i= value); for youtube a watch?v=, youtu.be/, /live/, /shorts/ or /embed/ URL. guid, podcastindex and hosting-platform values are used as given — a guid is whatever string the feed carries, which is often itself a URL, so it is never parsed. The identifier is echoed back exactly as supplied, not normalized. examples: - - '1000785846210' - '1000786587166' items: type: string maxItems: 100 minItems: 1 type: - array - 'null' responses: '200': content: application/json: schema: $ref: '#/components/schemas/EpisodeLookup' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: Error x-codeSamples: - label: cURL lang: curl source: |- curl -H "X-API-Key: $PARTICLE_API_KEY" \ "https://api.particle.pro/v1/podcasts/episodes/lookup?platform=apple&identifier=1000785846210%2C1000786587166" components: schemas: EpisodeLookup: additionalProperties: false properties: results: description: One result per unique input identifier, in request order items: $ref: '#/components/schemas/EpisodeLookupResult' type: - array - 'null' required: - results 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 EpisodeLookupResult: additionalProperties: false properties: episode: $ref: '#/components/schemas/EpisodeCompactWithPodcast' description: >- The matched episode, with its parent podcast. Omitted when the identifier does not resolve to any episode — callers should test for key presence rather than null. identifier: description: The platform-native identifier as supplied in the request type: string required: - identifier 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 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 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, and on endpoints that build this resource from a projection rather than the full podcast row. 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 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 ````