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`
Shows a guest could plausibly appear on next (the pitch list)	`GET /v1/podcasts/guests/{id}/recommendations/podcasts`
Guests a show could plausibly book (the booking pipeline)	`GET /v1/podcasts/{id}/recommendations/guests`

The {id} in every endpoint above is a Person reference (slug or encoded ID). The exceptions are the two podcast-keyed views, GET /v1/podcasts/{id}/guests and GET /v1/podcasts/{id}/recommendations/guests, where {id} is a podcast reference (slug, Particle ID, or Apple/iTunes ID) — they are the inverse views, listing the guests of a show and the guests a show could book.

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.

Recommended podcasts for a guest

GET /v1/podcasts/guests/{id}/recommendations/podcasts returns shows the person has not appeared on, ranked by how related they are to the shows the person has appeared on. It is the pitch list: where could this person plausibly go next, and which of their past venues make the case. Each recommendation is derived from the precomputed related set of the person’s own shows (see Related Podcasts) and carries a score in (0, 1), a band (strong, moderate, weak), and with include=via the person’s shows that led to it. Circuit regulars are discounted upstream, so the list reflects fit rather than fame.

curl "https://api.particle.pro/v1/podcasts/guests/brad-gerstner/recommendations/podcasts?include=via&limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response (truncated)

{
  "data": [
    {
      "podcast": { "id": "…", "title": "Invest Like the Best", "slug": "invest-like-the-best" },
      "score": 0.87,
      "band": "strong",
      "via": [
        { "id": "…", "title": "All-In with Chamath, Jason, Sacks & Friedberg", "slug": "all-in" },
        { "id": "…", "title": "BG2Pod", "slug": "bg2pod" }
      ]
    }
  ],
  "has_more": true,
  "cursor": "r.…"
}

Parameter	Meaning
`include`	`via` attaches the person’s own shows behind each recommendation, strongest first.
`limit`, `cursor`	Standard pagination over the ranked list (at most 200 recommendations per person).

A person with no identified appearances, or whose shows have no computed related set yet, gets 200 with an empty data array. The shows a person has already been on are at GET /v1/podcasts/guests/{id}/podcasts.

Recommended guests for a podcast

GET /v1/podcasts/{id}/recommendations/guests returns people who have guested on the show’s related shows but never on this one, ranked by how related those venues are and how established the person is on them. It is a booking pipeline, not a prediction: the right reading is “guests your peer shows book that you have not.” The podcast detail embeds the first five with include=recommended_guests on GET /v1/podcasts/{id}. Guests who appear everywhere (the podcast circuit’s regulars) are excluded, since recommending them says nothing about this show. Each row carries the person, a score and band, shared_show_count (how many related shows booked them), and with include=via which shows.

curl "https://api.particle.pro/v1/podcasts/all-in/recommendations/guests?include=via&limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response (truncated)

{
  "data": [
    {
      "person": { "id": "…", "name": "…", "slug": "…" },
      "score": 0.62,
      "band": "moderate",
      "shared_show_count": 3,
      "via": [
        { "id": "…", "title": "Invest Like the Best", "slug": "invest-like-the-best" }
      ]
    }
  ],
  "has_more": true,
  "cursor": "r.…"
}

Parameter	Meaning
`include`	`via` attaches the related shows that booked each person, strongest first.
`limit`, `cursor`	Standard pagination (at most 200 recommendations per show).

A show whose related set has not been computed yet gets 200 with an empty data array. The show’s existing roster is at GET /v1/podcasts/{id}/guests.

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

Recommended podcasts for a guest

Recommended guests for a podcast

​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

​Recommended podcasts for a guest

​Recommended guests for a podcast

​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

Recommended podcasts for a guest

Recommended guests for a podcast

Pagination

Related