> ## 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.
# External links
> Every third-party platform on which a podcast has a presence — directories, social profiles, video channels, websites — with resolved URLs and per-platform metadata.
A podcast lives in many places: it's on Apple Podcasts and Spotify, the host posts to X, the publisher runs a YouTube channel, and there's a marketing site on its own domain. The **external-links** endpoint returns every one of those presences in a single, normalized shape — with the platform-native identifier, a ready-to-use web URL, and a list of optional per-platform attributes (subscribers, followers, handle, etc.).
This page is the **forward** index: given a Particle podcast, list
every third-party identifier we have for it. To go the other way —
given an Apple, Spotify, or YouTube identifier, find the matching
Particle podcast (in bulk, deterministically) — use
[`GET /v1/podcasts/lookup`](/podcasts/lookup).
Use this endpoint when you want to:
* Build a "follow this podcast on…" UI without hard-coding per-platform URL templates.
* Compare audience size across platforms (Spotify followers vs. YouTube subscribers vs. Castbox subscribers).
* Pull the publisher's website and social handles for outreach or research.
* Reconcile a podcast across third-party catalogs (Apple ID ↔ Spotify show ID ↔ Podchaser ID). *If you start with the third-party identifier instead, use [`GET /v1/podcasts/lookup`](/podcasts/lookup) — it's the reverse direction of this same index.*
## List external links for a podcast
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/hard-fork/external-links" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/podcasts/hard-fork/external-links",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/podcasts/hard-fork/external-links",
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
The path parameter accepts a slug (`hard-fork`, `all-in`), the internal podcast ID, or a numeric Apple/iTunes collection ID — same as every other podcast sub-resource.
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"platform": {
"name": "apple",
"display_name": "Apple Podcasts",
"type": "podcast_directory"
},
"identifier": "1528594034",
"url": "https://podcasts.apple.com/podcast/id1528594034"
},
{
"platform": {
"name": "spotify",
"display_name": "Spotify",
"type": "music_service"
},
"identifier": "44fllCS2FTFr2x2kjP9xeT",
"url": "https://open.spotify.com/show/44fllCS2FTFr2x2kjP9xeT",
"attributes": [
{
"name": "followers",
"category": "audience_size",
"value": 3902,
"observed_at": "2026-04-22T11:00:00Z"
}
]
},
{
"platform": {
"name": "youtube",
"display_name": "YouTube",
"type": "video_channel"
},
"identifier": "UCZcR2SVWaGWNlMqPxvQS3vw",
"url": "https://www.youtube.com/channel/UCZcR2SVWaGWNlMqPxvQS3vw",
"attributes": [
{ "name": "handle", "category": "profile", "value": "hardfork" },
{ "name": "subscribers", "category": "audience_size", "value": 245000 },
{ "name": "videos", "category": "content", "value": 200 },
{ "name": "views", "category": "audience_size", "value": 12345678 }
]
},
{
"platform": { "name": "tiktok", "display_name": "TikTok", "type": "social_profile" },
"identifier": "hardfork",
"url": "https://www.tiktok.com/@hardfork"
},
{
"platform": { "name": "twitter", "display_name": "X (Twitter)", "type": "social_profile" },
"identifier": "HardFork",
"url": "https://twitter.com/HardFork"
},
{
"platform": { "name": "website", "display_name": "Website", "type": "website" },
"url": "https://www.nytimes.com/column/hard-fork"
}
// …
],
"has_more": false
}
```
Per-podcast cardinality is bounded — at most one entry per platform — so the endpoint returns the full set in a single response by default. Pass `?limit=` and `?cursor=` if you specifically want to page through results.
## Anatomy of an entry
Every entry has the same shape regardless of platform. Optional fields are omitted when no data is available.
| Field | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform.name` | Stable machine name (e.g. `spotify`, `youtube`). Suitable for filtering, routing, or persistence. |
| `platform.display_name` | Human-readable name suitable for UI display (`Apple Podcasts`, `X (Twitter)`). |
| `platform.type` | Broad category. Use this to group presences in a UI rather than enumerating every name. |
| `identifier` | Platform-native value (numeric id, slug, handle, or URL). Omitted entirely for the `website` platform — the JSON key is absent, not an empty string. |
| `url` | Canonical web URL for this presence. Built from a per-platform template, or passed through for `website`. |
| `attributes` | Optional per-platform metadata (audience size, profile fields, etc.). May be absent or empty. |
### Platform types
`platform.type` lets clients render related platforms with a shared treatment without knowing the full list of names:
| Type | What it covers |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `podcast_directory` | Apple Podcasts, Spotify-as-podcast-directory replicas, Castbox, Podchaser, Player FM, Podcast Addict, Podbean, Podcast Republic, Goodpods, The Podcast App, TuneIn, iHeartRadio. |
| `music_service` | Spotify, Apple Music–adjacent stores, Audible, Amazon Music — services whose primary brand is audio playback. |
| `social_profile` | X (Twitter), Instagram, Threads, TikTok, Facebook, LinkedIn — handle-based identity. |
| `video_channel` | YouTube channel for the podcast (and any future video-first platforms). |
| `community` | Reddit, Discord, Patreon — where listeners gather around the show. |
| `website` | The publisher's own marketing site for the podcast. The `identifier` is omitted; `url` carries the destination. |
| `other` | Reserved for future platforms that don't fit the above. Treat as opaque. |
### Attributes
Each entry's `attributes` is a list of typed records. The set of attribute names that may appear varies per platform — and grows over time as upstream sources expose richer metadata. Clients should treat unknown attribute names additively rather than enumerating them.
| Field | Description |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Platform-native attribute name (`subscribers`, `followers`, `handle`, etc.). |
| `category` | Broad grouping. Use this to render unfamiliar attributes without recognising the exact name. |
| `value` | The attribute value. JSON type matches the category — numbers for audience/content tallies, strings for profile/account fields, booleans for flags. |
| `observed_at` | ISO 8601 timestamp of when the attribute was last observed from the upstream source. Omitted when unavailable. |
#### Attribute categories
| Category | Typical names | Value type |
| ---------------- | ---------------------------------------------------- | -------------------------------------------- |
| `audience_size` | `subscribers`, `followers`, `views` | integer |
| `content` | `videos` | integer |
| `profile` | `handle`, `display_name`, `thumbnail_url`, `founded` | string (or RFC 3339 timestamp for `founded`) |
| `account_status` | `verified` (forthcoming) | boolean |
## Platform reference
The full list of platforms surfaced today, with the URL templates the API uses to build the `url` field. New platforms may be added without notice; existing platform names are stable.
| `name` | `display_name` | `type` | URL pattern |
| -------------- | ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `amazon_music` | Amazon Music | `music_service` | `https://music.amazon.com/podcasts/{id}` |
| `apple` | Apple Podcasts | `podcast_directory` | `https://podcasts.apple.com/podcast/id{id}` |
| `audible` | Audible | `music_service` | `https://www.audible.com/pd/{id}` |
| `castbox` | Castbox | `podcast_directory` | `https://castbox.fm/channel/id{id}` |
| `discord` | Discord | `community` | `https://discord.gg/{id}` |
| `facebook` | Facebook | `social_profile` | `https://www.facebook.com/{id}` |
| `goodpods` | Goodpods | `podcast_directory` | `https://www.goodpods.com/podcasts/{id}` |
| `iheartradio` | iHeartRadio | `podcast_directory` | `https://www.iheart.com/podcast/{id}/` |
| `instagram` | Instagram | `social_profile` | `https://www.instagram.com/{id}/` |
| `itunes` | iTunes | `podcast_directory` | `https://podcasts.apple.com/podcast/id{id}` |
| `linkedin` | LinkedIn | `social_profile` | `https://www.linkedin.com/company/{id}/` |
| `patreon` | Patreon | `community` | `https://www.patreon.com/{id}` |
| `playerfm` | Player FM | `podcast_directory` | `https://player.fm/series/{id}` |
| `podaddict` | Podcast Addict | `podcast_directory` | `https://podcastaddict.com/podcast/{id}` |
| `podbean` | Podbean | `podcast_directory` | `https://www.podbean.com/podcast-detail/{id}` |
| `podchaser` | Podchaser | `podcast_directory` | `https://www.podchaser.com/podcasts/{id}` |
| `podrepublic` | Podcast Republic | `podcast_directory` | `https://www.podcastrepublic.net/podcast/{id}` |
| `reddit` | Reddit | `community` | `https://www.reddit.com/r/{id}/` |
| `spotify` | Spotify | `music_service` | `https://open.spotify.com/show/{id}` |
| `threads` | Threads | `social_profile` | `https://www.threads.net/@{id}` |
| `tiktok` | TikTok | `social_profile` | `https://www.tiktok.com/@{id}` |
| `tpa` | The Podcast App | `podcast_directory` | `https://thepodcastapp.com/p/{id}` |
| `tunein` | TuneIn | `podcast_directory` | `https://tunein.com/podcasts/{id}/` |
| `twitter` | X (Twitter) | `social_profile` | `https://twitter.com/{id}` |
| `website` | Website | `website` | URL only; no separate `identifier` field |
| `youtube` | YouTube | `video_channel` | `https://www.youtube.com/channel/{id}` for channel-ID identifiers (`UC` + 22 chars), `https://www.youtube.com/@{id}` for handle identifiers |
## YouTube: richer attributes
YouTube is currently the most heavily-enriched platform. A YouTube entry can carry up to four attributes today:
```jsonc theme={"dark"}
{
"platform": { "name": "youtube", "display_name": "YouTube", "type": "video_channel" },
"identifier": "UCZcR2SVWaGWNlMqPxvQS3vw",
"url": "https://www.youtube.com/channel/UCZcR2SVWaGWNlMqPxvQS3vw",
"attributes": [
{ "name": "handle", "category": "profile", "value": "hardfork" },
{ "name": "subscribers", "category": "audience_size", "value": 245000 },
{ "name": "videos", "category": "content", "value": 200 },
{ "name": "views", "category": "audience_size", "value": 12345678 }
]
}
```
The `display_name`, `thumbnail_url`, and `founded` attributes may also appear when known.
## Notes and gotchas
### `apple` and `itunes` are usually duplicates
Apple Podcasts uses a single numeric ID across both its modern and iTunes-era surfaces. Most podcasts therefore have **two** entries — `apple` and `itunes` — with the same `identifier` and the same resolved `url`. This faithfully reflects what upstream catalog sources report; clients that want a single Apple entry can de-duplicate by `(type, identifier)`.
### Attributes are forward-compatible
Both `attributes[].name` and `attributes[].category` are open enumerations. New names (e.g. a future `engagement_rate` for Instagram) and new categories will be added without a versioning event. Always render unknown attributes additively — match on `category` for grouping when the name isn't recognized.
### `observed_at` is best-effort
Some attributes don't have a known observation timestamp; the field is then omitted. When present, the timestamp reflects the last time the value was refreshed from the upstream source — not the last time the *podcast* itself was updated.
### Identifier formats vary
The `identifier` is whatever the platform natively uses. Examples:
| Platform | Sample identifier | Shape |
| -------------------- | -------------------------- | ---------------------------------------------- |
| `apple` / `itunes` | `1528594034` | Numeric Apple Podcasts ID |
| `spotify` | `44fllCS2FTFr2x2kjP9xeT` | Spotify show ID |
| `youtube` | `UCZcR2SVWaGWNlMqPxvQS3vw` | Channel ID (or short handle for some podcasts) |
| `twitter` / `tiktok` | `HardFork` / `hardfork` | Account handle (no `@`) |
| `podbean` | `dir2423160,nrwgx` | Podbean-internal pair (don't try to parse) |
The `website` platform is the exception: there's no separate identifier — the entry omits `identifier` entirely and only carries `url`.
If you need a clickable link, prefer the resolved `url` over building one yourself; URL templates change.
## Choosing the right endpoint
| You want to… | Use this |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Show a "find this podcast on …" list of platforms (you have a Particle podcast → get all its external IDs) | `external-links` |
| **Reverse**: you have a third-party ID → resolve to a Particle podcast | [`GET /v1/podcasts/lookup`](/podcasts/lookup) |
| Compare audience size (followers / subscribers) across platforms | `external-links` (filter by `attributes[].category=audience_size`) |
| Get the podcast's own metadata (title, publisher, description, RSS feed, episode counts) | [`GET /v1/podcasts/{id}`](/podcasts/overview) |
| List episodes for a podcast | [`GET /v1/podcasts/{id}/episodes`](/podcasts/episodes) |
| Sponsor / advertising profile | [`GET /v1/podcasts/{id}/advertising`](/podcasts/advertising) |
| Political bias analysis | [`GET /v1/podcasts/{id}/bias`](/podcasts/overview#bias-analysis) |
## Related
* [Lookup by external ID](/podcasts/lookup) — the reverse direction of this index: third-party identifier → Particle podcast.
* [Podcasts overview](/podcasts/overview) — full Podcast object and other sub-resources.
* [Episodes](/podcasts/episodes) — drill from a podcast into its individual episodes.
* [Knowledge graph → entities](/knowledge-graph/entities) — the canonical record for the podcast's hosts, guests, and topics.