particle_podcast_list_guests

Browse podcast guests across the catalog — the directory by lifetime appearances, filtered by expertise if you like, or who’s trending right now.

Browse podcast guests across the catalog, in two opinionated modes:

• directory (default): the guest directory ranked by lifetime appearances (guests with 2+ appearances).
• trends: who’s making the rounds right now — guests with appearances on 2+ distinct podcasts in the last 30 days, which surfaces cross-show press tours rather than show regulars. The press-tour shape is enforced by several baked filters: every in-window appearance must be on a different podcast (no stacking repeats on one show), each appearance needs 5+ minutes of identified speaking time, mononymous catch-all people are excluded, and the in-window rate must be at least a 2× spike over the guest’s lifetime baseline. A guest matching the headline criteria but failing any of these will not appear.

podcast_slug switches the listing from the corpus to one show’s guest roster: every guest who has appeared on that podcast, ranked by appearances on the show — with no lifetime-appearance floor, so one-off guests are included. It only combines with the default directory mode (trends is corpus-wide and has no podcast filter — combining them is an invalid_input error).

topic_slug narrows either corpus mode to guests appearing on episodes about that topic (it is ignored when podcast_slug is set). Guest identifiers are person handles — usually the canonical person slug, falling back to the encoded person ID when a slug hasn’t been backfilled yet (both forms are accepted everywhere a person is taken). Feed them into particle_podcast_get_guest for the appearance profile or particle_person_get for the person profile.

Filtering by expertise

The directory takes speaker-expertise filters: occupation, field, standing, seniority, practicing, capacity and employer, plus appeared_since for guests seen recently. occupation and field take a code, slug or title from particle_expertise_resolve, and a broad code covers everything below it. include: ["expertise"] adds each guest’s read on one line: standing, seniority, most specific occupation and field, and organization.

• One-off guests are kept. An expertise filter already says who belongs, so a filtered directory drops the two-appearance floor: a practicing cardiologist who guested once is the answer.
• practicing needs a detailed SOC 2018 occupation, such as 29-1212 Cardiologists. With a broader code, or with no occupation, it returns validation_error.
• With podcast_slug, the filters list that show’s guests through the directory, so the rows carry directory stats rather than roster stats; one-off guests are kept, as on the roster. Without any filter, podcast_slug returns the plain roster as before.
• These filters, appeared_since and include are directory-only. Combining any of them with mode="trends" returns invalid_input.
• An occupation or field that names nothing returns unresolved_reference with the closest codes as did-you-mean suggestions.

Beyond the expertise filters, this surface is deliberately minimal: a podcast filter (podcast_slug for one show’s roster), a topic filter, and pagination. The unfiltered directory uses lifetime appearance counts (floor of 2 appearances); trends uses a 30-day window with a 2+ distinct-podcast bar. The full filter surface lives on the REST API.

Inputs

Field	Type	Required	Default	Description
mode	string	no	directory	What to return: directory (lifetime appearances) or trends (last-30-day cross-show press tours).
podcast_slug	string	no	—	Return one show’s guest roster (every guest who has appeared on the podcast, ranked by on-show appearances, one-offs included). Slug from particle_podcast_resolve. Directory mode only.
topic_slug	string	no	—	Restrict to guests with appearances on episodes classified under this topic (slug from particle_topic_browse, e.g. "technology/artificial-intelligence"). Ignored when podcast_slug is set.
occupation	string	no	—	Only guests listed under this occupation: a SOC 2018 or ISCO-08 code, slug or title from particle_expertise_resolve (e.g. "cardiologists" or "29-1212"). Directory mode only.
field	string	no	—	Only guests listed under this ANZSRC 2020 field of research: a code, slug or title from particle_expertise_resolve (e.g. "banking-finance-and-investment"). Directory mode only.
standing	string	no	—	Only guests whose standing is recognized this way: established (conferred by others: a credential, a position, recognition in the field), self_described, or unverified. Directory mode only.
seniority	string	no	—	Only guests at this seniority or above: professional, senior, or distinguished. Directory mode only.
practicing	boolean	no	false	Only guests who still work in the occupation. Needs a detailed SOC 2018 occupation (e.g. "29-1212"). Directory mode only.
capacity	string	no	—	Only guests who know their field in this capacity: researcher, licensed_professional, practitioner, executive_founder, public_official, journalist_analyst, creator_entertainer, athlete_coach, clergy, firsthand, or layperson. Directory mode only.
employer	string	no	—	Only guests whose organization is this company (slug from particle_company_resolve, or a domain). Directory mode only.
appeared_since	string	no	—	Only guests with an appearance on or after this date (YYYY-MM-DD or ISO 8601). Directory mode only.
include	array of enums	no	[]	Optional per-guest sections: expertise (each guest’s standing, seniority, most specific occupation and field, and organization on one line). Directory mode only.
limit	integer (1–50)	no	20	Guests per page.
cursor	string	no	—	Opaque pagination cursor.

Output

A markdown document with ## Podcast guests — <mode> (N) (or ## Guest roster — <podcast_slug> (N) when podcast_slug is set) and a flat bullet list — one bullet per guest, formatted **Name** (slug) — <stats>. In directory mode <stats> is N appearances across M podcasts, last YYYY-MM-DD; in trends mode it is N podcasts in the last 30 days, M lifetime appearances, last YYYY-MM-DD. The parenthesized identifier is the canonical person slug when one has been backfilled, otherwise the encoded person ID — both forms are accepted everywhere a person is taken (guest_slug, person_slug, particle_person_get). Each bullet of a guest with an expertise profile ends with — expertise: <Occupation> (<code>), practicing · field <Field> (<code>) · <standing> · <seniority>; with include: ["expertise"] (directory mode) the suffix widens to <standing> · <seniority> · <Occupation> (<code>), <flags> · field <Field> (<code>) · at <Organization>. Either leaves out any part the read does not have; a guest not read yet has no suffix. When more pages exist, a horizontal rule and a **Cursor:** <value> line are appended.

Sample (mode=trends, limit=3):

## Podcast guests — trends (3)

- **Sam Altman** (sam-altman) — 4 podcasts in the last 30 days, 38 lifetime appearances, last 2026-05-28
- **Cathie Wood** (cathie-wood) — 3 podcasts in the last 30 days, 21 lifetime appearances, last 2026-05-26
- **Marc Andreessen** (marc-andreessen) — 2 podcasts in the last 30 days, 15 lifetime appearances, last 2026-05-22

Sample (occupation="29-1212", practicing=true, appeared_since="2026-09-01", include=["expertise"], limit=2):

## Podcast guests — directory (2)

- **Eric Topol** (eric-topol) — 41 appearances across 29 podcasts, last 2026-10-03 — expertise: established · distinguished · Cardiologists (29-1212), established, practicing · field Cardiology (incl. cardiovascular diseases) (320101) · at Scripps Research
- **Jane Doe** (jane-doe) — 1 appearances across 1 podcasts, last 2026-09-18 — expertise: established · professional · Cardiologists (29-1212), established, practicing · at Mayo Clinic

Example

Agent calls: particle_podcast_list_guests {
  "mode": "directory",
  "topic_slug": "technology/artificial-intelligence",
  "limit": 25
}

Practicing cardiologists who guested recently:

Agent calls: particle_podcast_list_guests {
  "occupation": "cardiologists",
  "practicing": true,
  "appeared_since": "2026-09-01",
  "include": ["expertise"]
}

Related

• REST equivalent: GET /v1/podcasts/guests for mode="directory"; GET /v1/podcasts/guests/trends for mode="trends"; GET /v1/podcasts/{id}/guests for podcast_slug rosters.
• For a single guest’s appearance profile, use particle_podcast_get_guest.
• Find an occupation or field code with particle_expertise_resolve; for the guests most booked under one code in a recent window, use particle_expertise_get with include: ["top_guests"]. The REST filters are documented under the guest directory.
• Browse the topic taxonomy with particle_topic_browse.