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.
topic_slug narrows either mode to guests appearing on episodes about that topic. 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.
This surface is deliberately minimal — only a topic filter and pagination. The 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). |
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"). |
limit | integer (1–50) | no | 20 | Guests per page. |
cursor | string | no | — | Opaque pagination cursor. |
Output
A markdown document with## Podcast guests — <mode> (N) 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). When more pages exist, a horizontal rule and a **Cursor:** <value> line are appended.
Sample (mode=trends, limit=3):
Example
Related
- REST equivalent:
GET /v1/podcasts/guestsformode="directory";GET /v1/podcasts/guests/trendsformode="trends". - For a single guest’s appearance profile, use
particle_podcast_get_guest. - Browse the topic taxonomy with
particle_topic_browse.