> ## 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. # Guests > Track the people who appear on podcasts — lifetime profiles, every appearance, the shows they join, who's doing the rounds, and brand-suitability exposure. 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](/podcasts/mentions), 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](#trending-guests), the signal behind a book launch or product unveil. * **Brand-safety screening** — read a guest's [suitability exposure](#brand-suitability-exposure) across the shows they join before a sponsorship or partnership. * **Talent graphs** — pivot from a podcast to its [guest roster](#guest-roster-for-a-podcast) and back out to each guest's wider footprint. ## Choosing the right endpoint | You want… | Use this | | ------------------------------------------------ | ------------------------------------------------------------------------- | | Browse or search the directory of podcast guests | [`GET /v1/podcasts/guests`](#the-guest-directory) | | A single guest's lifetime profile and stats | [`GET /v1/podcasts/guests/{id}`](#a-guest-profile) | | Every episode a guest appeared on | [`GET /v1/podcasts/guests/{id}/appearances`](#appearances) | | The distinct shows a guest has appeared on | [`GET /v1/podcasts/guests/{id}/podcasts`](#podcasts-a-guest-has-joined) | | Who has been a guest on a specific podcast | [`GET /v1/podcasts/{id}/guests`](#guest-roster-for-a-podcast) | | Guests currently doing the podcast rounds | [`GET /v1/podcasts/guests/trends`](#trending-guests) | | A guest's brand-suitability exposure | [`GET /v1/podcasts/guests/{id}/suitability`](#brand-suitability-exposure) | 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`](#guest-roster-for-a-podcast), 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. ```bash curl theme={"dark"} 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" ``` ```js JavaScript theme={"dark"} const params = new URLSearchParams({ q: "gerstner", min_appearances: "5" }); const res = await fetch( `https://api.particle.pro/v1/podcasts/guests?${params}`, { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } }, ); const { data } = await res.json(); ``` ```python Python theme={"dark"} import os, requests res = requests.get( "https://api.particle.pro/v1/podcasts/guests", params={"q": "gerstner", "min_appearances": 5}, headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) guests = res.json()["data"] ``` ```json Response theme={"dark"} { "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](#a-guest-profile) to expand it. ### Filters | Param | Notes | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `q` | Case-insensitive substring match on the guest's display name. | | `min_appearances` | Minimum lifetime appearance count. Default 1. | | `podcast_id` | Slug or ID. Restrict to guests who have appeared on this podcast. When set, `appearance_count` is scoped to that show. | | `topic_id` | Restrict to guests with at least one appearance on an episode under this topic. | | `appeared_since` | ISO 8601 date. Guests with an appearance on or after this date. | | `suitability_tier_max` | `SAFE`, `LIMITED`, `SENSITIVE`, `UNSAFE`. Restrict to guests whose appearances are on shows at or below this IAB Tech Lab tier. | | `sort` | `appearances` (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. ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/guests/brad-gerstner" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```json Response (truncated) theme={"dark"} { "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](/knowledge-graph/entities) 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. ```bash theme={"dark"} 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" ``` ```json Response (truncated) theme={"dark"} { "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 | Param | Notes | | -------------------------------------- | -------------------------------------------------------------------- | | `podcast_id` | Slug or ID. Restrict to appearances on one podcast. | | `topic_id` | Restrict to appearances on episodes under this topic. | | `published_after` / `published_before` | ISO 8601 dates bounding the episode publication window. | | `suitability_tier_max` | `SAFE`, `LIMITED`, `SENSITIVE`, `UNSAFE`. | | `min_speaking_seconds` | Only 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. ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/guests/brad-gerstner/podcasts" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```json Response (truncated) theme={"dark"} { "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. ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/all-in/guests" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```json Response (truncated) theme={"dark"} { "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. ## Trending guests `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. ```bash theme={"dark"} curl --get "https://api.particle.pro/v1/podcasts/guests/trends" \ --data-urlencode "min_distinct_podcasts=3" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```json Response (truncated) theme={"dark"} { "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`](#the-guest-directory) instead. ### Filters | Param | Notes | | ------------------------ | -------------------------------------------------------------------------------------------------------- | | `since` | ISO 8601 date. Inclusive lower bound of the window. Default: 30 days ago. | | `min_distinct_podcasts` | Minimum distinct shows inside the window. Minimum 2, default 2. | | `first_appearance_since` | Restrict to guests whose earliest-ever appearance is on or after this date — the "new on the scene" cut. | | `topic_id` | Restrict to in-window appearances on episodes under this topic. | | `suitability_tier_max` | `SAFE`, `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. ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/guests/brad-gerstner/suitability" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```json Response (truncated) theme={"dark"} { "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. ## Related * [Mentions](/podcasts/mentions) — every line where a person or company is named, host or guest. * [Brand Suitability](/podcasts/suitability) — the per-show assessment behind a guest's exposure profile. * [Episodes](/podcasts/episodes) — episode discovery, including `entity_id` recall by speaker. * [Knowledge graph entities](/knowledge-graph/entities) — the optional `knowledge_graph_entity` cross-reference attached to some guests.