Guests

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 guests	`GET /v1/podcasts/guests`
A single guest’s lifetime profile and stats	`GET /v1/podcasts/guests/{id}`
Every episode a guest appeared on	`GET /v1/podcasts/guests/{id}/appearances`
The distinct shows a guest has appeared on	`GET /v1/podcasts/guests/{id}/podcasts`
Who has been a guest on a specific podcast	`GET /v1/podcasts/{id}/guests`
Guests currently doing the podcast rounds	`GET /v1/podcasts/guests/trends`
A guest’s brand-suitability exposure	`GET /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"

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();

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"]

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

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.

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

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.

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

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.

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.

Getting started

Podcasts

Companies

Knowledge graph

Alerts

Errors

What you can build

Choosing the right endpoint

The guest directory

Filters

A guest profile

Appearances

Filters

Podcasts a guest has joined

Guest roster for a podcast

Filters

Brand-suitability exposure

​What you can build

​Choosing the right endpoint

​The guest directory

​Filters

​A guest profile

​Appearances

​Filters

​Podcasts a guest has joined

​Guest roster for a podcast

​Trending guests

​Filters

​Brand-suitability exposure

​Pagination

​Related

What you can build

Choosing the right endpoint

The guest directory

Filters

A guest profile

Appearances

Filters

Podcasts a guest has joined

Guest roster for a podcast

Trending guests

Filters

Brand-suitability exposure

Pagination

Related