Skip to main content

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.

A guest is a Person — Particle’s first-class entity for an individual, served in full at GET /v1/people/{id} — identified in a non-host listing role on at least one episode. The guest endpoints are built around that Person identity: every guest carries the same canonical handle used everywhere else on the platform, so the speaker you find in a transcript, the person served by the People API, and the guest in this directory are the same record. Resolve a guest by slug (recommended — e.g. brad-gerstner) or by the encoded Person ID returned as id.
A guest is someone who appeared on an episode in a listing role — distinct from a mention, which is any line of dialogue where a person is named, whether they’re in the room or not. Use Guests to follow who shows up; use Mentions to follow who gets talked about.

​
What you can build

  • Booking and PR research — find a guest’s complete appearance history, the shows they favor, and who else those shows book.
  • Press-tour detection — surface people making the rounds right now with trends, the signal behind a book launch or product unveil.
  • Brand-safety screening — read a guest’s suitability exposure across the shows they join before a sponsorship or partnership.
  • Talent graphs — pivot from a podcast to its guest roster and back out to each guest’s wider footprint.

​
Choosing the right endpoint

You want…Use this
Browse or search the directory of podcast guestsGET /v1/podcasts/guests
A single guest’s lifetime profile and statsGET /v1/podcasts/guests/{id}
Every episode a guest appeared onGET /v1/podcasts/guests/{id}/appearances
The distinct shows a guest has appeared onGET /v1/podcasts/guests/{id}/podcasts
Who has been a guest on a specific podcastGET /v1/podcasts/{id}/guests
Guests currently doing the podcast roundsGET /v1/podcasts/guests/trends
A guest’s brand-suitability exposureGET /v1/podcasts/guests/{id}/suitability
The {id} in every endpoint above is a Person reference (slug or encoded ID). The one exception is the roster endpoint, GET /v1/podcasts/{id}/guests, where {id} is a podcast reference (slug, Particle ID, or Apple/iTunes ID) — it’s the inverse view, listing the guests of a show.

​
The guest directory

GET /v1/podcasts/guests returns a paginated directory of everyone who has guested on the catalog, ranked by lifetime appearances by default. 
curl --get "https://api.particle.pro/v1/podcasts/guests" \
  --data-urlencode "q=gerstner" \
  --data-urlencode "min_appearances=5" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response
{
  "data": [
    {
      "id": "5njEX8HDc7oNdM8kr9ItRs",
      "slug": "brad-gerstner",
      "name": "Brad Gerstner",
      "appearance_count": 35,
      "distinct_podcasts": 10,
      "first_appearance_at": "2020-11-04T10:06:21Z",
      "last_appearance_at": "2026-05-29T22:16:05Z"
    }
  ],
  "has_more": false
}
Each row is a compact guest: the Person identity (id, slug, name, and image_url when a headshot is known) plus lifetime appearance_count and distinct_podcasts. Pass any slug or id straight into the profile endpoint to expand it.

​
Filters

ParamNotes
qCase-insensitive substring match on the guest’s display name.
min_appearancesMinimum lifetime appearance count. Default 1.
podcast_idSlug or ID. Restrict to guests who have appeared on this podcast. When set, appearance_count is scoped to that show.
topic_idRestrict to guests with at least one appearance on an episode under this topic.
appeared_sinceISO 8601 date. Guests with an appearance on or after this date.
suitability_tier_maxSAFE, LIMITED, SENSITIVE, UNSAFE. Restrict to guests whose appearances are on shows at or below this IAB Tech Lab tier.
sortappearances (default) or recency.

​
A guest profile

GET /v1/podcasts/guests/{id} returns the lifetime profile: the full Person payload — the same one served at /v1/people/{id} — plus a podcast-guest activity block. 
curl "https://api.particle.pro/v1/podcasts/guests/brad-gerstner" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "id": "5njEX8HDc7oNdM8kr9ItRs",
  "slug": "brad-gerstner",
  "name": "Brad Gerstner",
  "description": "Founder, Chairman, and CEO of Altimeter Capital; co-host of BG2Pod",
  "detailed_description": "Brad Gerstner is an American entrepreneur, investor, and hedge fund manager who founded Altimeter Capital…",
  "external_links": [
    { "platform": { "name": "linkedin", "display_name": "LinkedIn", "type": "social_profile" }, "identifier": "in/bradgerstner", "url": "https://www.linkedin.com/in/bradgerstner/" },
    { "platform": { "name": "wikipedia", "display_name": "Wikipedia", "type": "other" }, "url": "https://en.wikipedia.org/wiki/Brad_Gerstner" }
  ],
  "knowledge_graph_entity": {
    "id": "1GmOP1C2tsrQUoriBU",
    "slug": "brad-gerstner",
    "wikipedia_url": "https://en.wikipedia.org/wiki/Brad_Gerstner"
  },
  "stats": {
    "appearance_count": 35,
    "distinct_podcasts": 10,
    "first_appearance_at": "2020-11-04T10:06:21Z",
    "last_appearance_at": "2026-05-29T22:16:05Z",
    "total_speaking_seconds": 28012.23,
    "appearances_by_bias": { "NOT_POLITICAL": 3, "CENTER": 4, "LEANS_LEFT": 2, "LEANS_RIGHT": 19, "RIGHT": 7 },
    "appearances_by_suitability_tier": { "SAFE": 28, "LIMITED": 5, "SENSITIVE": 2 }
  },
  "top_podcasts": [
    {
      "podcast": { "id": "4t9PU1WkzOroEXfBl6ia7r", "title": "All-In with Chamath, Jason, Sacks & Friedberg", "slug": "all-in", "image_url": "https://cdn.particle.pro/url/media/a0a7b2fa-…" },
      "appearance_count": 19,
      "first_appearance_at": "2020-11-04T10:06:21Z",
      "last_appearance_at": "2026-05-08T22:16:00Z",
      "suitability_tier": "SAFE",
      "bias": "LEANS_RIGHT"
    }
  ]
}
The Person fields (description, detailed_description, external_links, and — when a company affiliation is known — current_role and roles) carry the guest’s identity. knowledge_graph_entity is an optional secondary identifier — a knowledge graph entity cross-reference attached to some people — not the Person itself; rely on id/slug to identify a guest. The stats block is the guest-specific part:
  • appearances_by_bias buckets appearances by the political-bias rating of the host show. Keys include NOT_POLITICAL (the dominant bucket for most guests, since most shows aren’t political) alongside EXTREME_LEFT … EXTREME_RIGHT, so the political mix is contextualized. Counts sum to at most appearance_count — appearances on shows whose bias hasn’t been evaluated are omitted.
  • appearances_by_suitability_tier does the same for the IAB Tech Lab brand-suitability tier (SAFE, LIMITED, SENSITIVE, UNSAFE).
  • top_podcasts is the (up to five) most-frequent shows, each with the guest’s per-show appearance count and the show’s suitability_tier and bias.
A guest profile returns 404 when the Person exists but has never appeared as a guest, so a 200 is itself confirmation of guest activity.

​
Appearances

GET /v1/podcasts/guests/{id}/appearances lists the episodes a guest appeared on, most recent first. 
curl --get "https://api.particle.pro/v1/podcasts/guests/brad-gerstner/appearances" \
  --data-urlencode "min_speaking_seconds=120" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "episode": {
        "id": "1lYfNtoWjotDDGoK77IAc4",
        "title": "Crypto Fueling a War",
        "slug": "crypto-fueling-a-war-2",
        "published_at": "2026-05-22T17:16:40Z",
        "duration_seconds": 2296
      },
      "podcast": {
        "id": "6aSPee2tS89h0BMiIjlA6X",
        "title": "Armstrong & Getty Podcast",
        "slug": "armstrong-and-getty",
        "image_url": "https://cdn.particle.pro/url/media/d876513c-…"
      },
      "speaking_seconds": 345.95,
      "suitability_tier": "SAFE",
      "bias": "RIGHT"
    }
  ],
  "has_more": true,
  "cursor": "r.4gfFC6"
}
Each row pairs the episode with the podcast that published it, the guest’s identified speaking_seconds on that episode, and the show’s suitability_tier and bias.

​
Filters

ParamNotes
podcast_idSlug or ID. Restrict to appearances on one podcast.
topic_idRestrict to appearances on episodes under this topic.
published_after / published_beforeISO 8601 dates bounding the episode publication window.
suitability_tier_maxSAFE, LIMITED, SENSITIVE, UNSAFE.
min_speaking_secondsOnly appearances with identified speaking time above this threshold.

​
Podcasts a guest has joined

GET /v1/podcasts/guests/{id}/podcasts returns the distinct set of shows a guest has appeared on, with a per-show rollup. 
curl "https://api.particle.pro/v1/podcasts/guests/brad-gerstner/podcasts" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "podcast": {
        "id": "4t9PU1WkzOroEXfBl6ia7r",
        "title": "All-In with Chamath, Jason, Sacks & Friedberg",
        "slug": "all-in",
        "image_url": "https://cdn.particle.pro/url/media/a0a7b2fa-…"
      },
      "appearance_count": 19,
      "first_appearance_at": "2020-11-04T10:06:21Z",
      "last_appearance_at": "2026-05-08T22:16:00Z",
      "suitability_tier": "SAFE",
      "bias": "LEANS_RIGHT"
    }
  ],
  "has_more": false
}
This is the aggregate behind top_podcasts on the profile, but unbounded and paginated — every show, not just the top five.

​
Guest roster for a podcast

GET /v1/podcasts/{id}/guests is the inverse pivot: the identified guests of a given show. Here {id} is a podcast reference. 
curl "https://api.particle.pro/v1/podcasts/all-in/guests" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "id": "5njEX8HDc7oNdM8kr9ItRs",
      "slug": "brad-gerstner",
      "name": "Brad Gerstner",
      "appearance_count": 19,
      "distinct_podcasts": 10,
      "first_appearance_at": "2020-11-04T10:06:21Z",
      "last_appearance_at": "2026-05-08T22:16:00Z"
    }
  ],
  "has_more": true,
  "cursor": "r.4gfFC6"
}
The rows are the same compact guest shape as the directory, but here appearance_count is scoped to this show (Brad Gerstner’s 19 appearances on All-In), while distinct_podcasts stays his lifetime count across the catalog. Returns 404 when the podcast can’t be resolved. GET /v1/podcasts/guests/trends surfaces guests who are currently making the rounds — the cross-show interview activity that signals a book launch, product unveil, news-cycle moment, or new-on-the-scene debut. 
curl --get "https://api.particle.pro/v1/podcasts/guests/trends" \
  --data-urlencode "min_distinct_podcasts=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "guest": {
        "id": "57kYjDofrt8lUZgIDz4qMb",
        "slug": "david-epstein",
        "name": "David Epstein",
        "appearance_count": 30,
        "distinct_podcasts": 29,
        "last_appearance_at": "2026-05-25T07:00:00Z"
      },
      "recent_appearances": 20,
      "first_appearance_in_window": "2026-05-04T07:03:00Z",
      "last_appearance_at": "2026-05-25T07:00:00Z"
    }
  ],
  "has_more": true,
  "cursor": "r.4gfFC7"
}
guest carries lifetime stats; recent_appearances is the count inside the window. Every in-window appearance is on a distinct show — guests with repeats on the same show inside the window are excluded — so the number doubles as “distinct podcasts this window.”
This is not a leaderboard of perennial regulars. Recurring co-hosts and daily news-segment contributors are filtered out by design: a guest must show activity materially elevated above their own baseline, across multiple distinct shows, with substantive (5+ minute) interviews. For a steady-state directory, use GET /v1/podcasts/guests instead.

​
Filters

ParamNotes
sinceISO 8601 date. Inclusive lower bound of the window. Default: 30 days ago.
min_distinct_podcastsMinimum distinct shows inside the window. Minimum 2, default 2.
first_appearance_sinceRestrict to guests whose earliest-ever appearance is on or after this date — the “new on the scene” cut.
topic_idRestrict to in-window appearances on episodes under this topic.
suitability_tier_maxSAFE, LIMITED, SENSITIVE, UNSAFE.

​
Brand-suitability exposure

GET /v1/podcasts/guests/{id}/suitability returns the distribution of IAB Tech Lab brand-suitability tiers across the shows a guest has appeared on, plus the categories most often flagged in those shows. 
curl "https://api.particle.pro/v1/podcasts/guests/brad-gerstner/suitability" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "lifetime": {
    "tier_distribution": [
      { "tier": "SAFE", "episodes": 28, "distinct_podcasts": 6 },
      { "tier": "LIMITED", "episodes": 5, "distinct_podcasts": 2 },
      { "tier": "SENSITIVE", "episodes": 2, "distinct_podcasts": 2 }
    ]
  },
  "recent_90d": {
    "window_start": "2026-03-03T02:50:50Z",
    "tier_distribution": [
      { "tier": "SAFE", "episodes": 11, "distinct_podcasts": 4 }
    ]
  },
  "top_categories": [
    { "code": "death_injury_military_conflict", "prevalence": "FREQUENT", "treatment": "DOCUMENTARY", "podcasts": 6 },
    { "code": "debated_social_issues", "prevalence": "FREQUENT", "treatment": "EDITORIAL", "podcasts": 4 }
  ],
  "notes": "This response measures the guest's exposure across the shows they have appeared on. The brand-safety tier of a show reflects the show's overall content profile and is not a verdict on any individual guest. Appearing on a SENSITIVE- or UNSAFE-tier show does not imply the guest is unsuitable."
}
Both a lifetime and a trailing recent_90d window are returned; each buckets the guest’s appearances by tier with episode and distinct-podcast counts. top_categories lists the most-flagged IAB categories with their prevalence (INCIDENTAL, OCCASIONAL, FREQUENT, PERVASIVE) and dominant treatment.
This endpoint measures exposure, not a verdict on the guest. A show’s brand-safety tier reflects the show’s overall content profile — appearing on a SENSITIVE- or UNSAFE-tier show does not imply the guest is unsuitable. The notes field restates this in every response.

​
Pagination

The list endpoints use the standard envelope: limit (1–100, default 25) plus an opaque cursor, returning { data, has_more, cursor }. Pass the cursor from one response back as ?cursor=… to fetch the next page. The single-item endpoints — the profile and the suitability exposure — are not paginated.
  • Mentions — every line where a person or company is named, host or guest.
  • Brand Suitability — the per-show assessment behind a guest’s exposure profile.
  • Episodes — episode discovery, including entity_id recall by speaker.
  • Knowledge graph entities — the optional knowledge_graph_entity cross-reference attached to some guests.