particle_podcast_get_episode_timeseries

Time-bucketed episode counts — appearance, publication, and topic trend lines per day, week, or month.

Time-bucketed episode counts — the purpose-built answer to “how often is X discussed over time”. Counts episodes matching the same filters as particle_podcast_list_episodes (person, company, entity, podcast, keyword, guests’ expertise, language, duration, transcript availability) per day, week, or month, plus range totals. keyword_search additionally counts matching transcript segments per bucket — exact counts, no pagination floors. semantic_search does the same by meaning — same embedding and similarity threshold as particle_podcast_search_transcripts, so the counts agree with search results (for pathologically broad queries the mention counts can be lower bounds); it requires published_after and cannot be combined with keyword_search.

Use this for trend charts instead of paging particle_podcast_list_episodes or particle_podcast_find_mentions once per period. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks; a published_after/published_before inside a bucket produces a partial first or last bucket labeled with the full bucket’s start date. Omitting published_after aggregates all time — except with semantic_search, which always requires the lower bound. Ranges are capped at 1000 buckets.

At least one subject filter is required: podcast_slug, person_slug, company_slug, entity_slug, keyword_search, semantic_search, guest_occupation, or guest_field.

The guest_ filters count episodes by their guests’ expertise, with codes from particle_expertise_resolve. guest_occupation and guest_field count as a subject: guest_field alone charts how often a field’s experts are booked, and with company_slug it charts the company’s episodes featuring those experts. The other guest_ filters (guest_standing, guest_seniority, guest_capacity, guest_practicing, guest_in_field) only narrow a subject, so on their own they return missing_parameter; so does a guest_occupation that names a capacity, such as founders. Resolve the words to codes with particle_expertise_resolve first; on unresolved_reference, resolve and retry.

The guest_ filters are episode-level and never check who spoke. With keyword_search, a matching segment counts when its episode had such a guest, even if the host said the words, so the count is not “what the experts said”. For who said a keyword, use particle_podcast_get_share_of_voice with keyword_search.

Inputs

Field	Type	Required	Default	Description
podcast_slug	string	one subject filter required	—	Podcast slug, internal ID, or numeric iTunes ID.
person_slug	string	one subject filter required	—	Person slug or encoded person ID (e.g. "sam-altman"). Counts episodes featuring the person as a speaker — and, when the person has a linked knowledge-graph entity, episodes that mention them.
company_slug	string	one subject filter required	—	Company slug, domain, or ID. Resolves to the linked entity.
entity_slug	string	one subject filter required	—	Knowledge-graph entity slug for the long tail that isn’t a person or company (e.g. "germany").
keyword_search	string	one subject filter required	—	Keyword filter over transcript content. Double-quoted substrings must appear as exact phrases; unquoted terms must all appear in one transcript segment. Adds per-bucket mention counts. Cannot be combined with semantic_search.
semantic_search	string	one subject filter required	—	Vector-similarity filter by meaning over transcript content. Describe the topic conversationally; paraphrase tolerant. Adds per-bucket mention counts. Requires published_after (ranges up to ~2 years). Cannot be combined with keyword_search.
role	string	no	—	Role filter when a person/company/entity filter is set: guest, host, panelist, correspondent, or mention.
published_after	string	no	all time	Inclusive range start (ISO 8601 date or date-time).
published_before	string	no	now	Range end (ISO 8601 date or date-time).
interval	string	no	week	Bucket width: day, week, or month.
language	string	no	—	Restrict to episodes of podcasts in this language — ISO 639-1 code (e.g. "fr"). Matches the podcast’s primary language subtag, so fr covers fr-FR.
has_transcript	boolean	no	false	Only count episodes with a completed transcript.
min_duration / max_duration	integer	no	—	Episode duration bounds in seconds.
guest_occupation	string	one subject filter required	—	Only episodes with a guest listed under this occupation: a SOC 2018 or ISCO-08 code, slug or title from particle_expertise_resolve (e.g. "cardiologists" or "29-1212"). Counts as a subject filter.
guest_field	string	one subject filter required	—	Only episodes with a guest listed under this ANZSRC 2020 field of research: a code, slug or title from particle_expertise_resolve (e.g. "banking-finance-and-investment"). Counts as a subject filter.
guest_standing	string	no	—	Only episodes with a guest whose standing is recognized this way: established (conferred by others), self_described, or unverified.
guest_seniority	string	no	—	Only episodes with a guest at this seniority or above: professional, senior, or distinguished.
guest_capacity	string	no	—	Only episodes with a guest who knows their field in this capacity: researcher, licensed_professional, practitioner, executive_founder, public_official, journalist_analyst, creator_entertainer, athlete_coach, clergy, firsthand, or layperson. particle_expertise_resolve names the capacity an everyday word means (founders is executive_founder).
guest_practicing	boolean	no	false	Only episodes with a guest who still works in guest_occupation, which must be a detailed SOC 2018 occupation (e.g. "29-1212").
guest_in_field	boolean	no	false	Only episodes with a guest speaking within their own field (the guest the other guest_ filters select, when given).

All guest_ filters describe the same guest, so guest_occupation="cardiologists" with guest_practicing=true keeps episodes where one guest is a practicing cardiologist. A broad code covers everything below it. A word no occupation names may name a field or a capacity instead, and filters by it: guest_occupation="oncologists" is field 3211, guest_occupation="founders" is guest_capacity="executive_founder". An occupation or field that names nothing returns unresolved_reference with the closest codes as did-you-mean suggestions; guest_practicing without a detailed SOC 2018 guest_occupation returns validation_error.

Output

A markdown document with ## Episode timeseries — per <interval>, **Range:**, **Total episodes:**, and **Distinct podcasts:** rows (plus **Total mentions:** when keyword_search or semantic_search is set, and a **Counts:** row when a broad semantic_search matched more segments than it could count in time, so the counts are lower bounds), followed by a table of buckets — Bucket | Episodes columns, with a Mentions column added when keyword_search or semantic_search is set. Buckets are contiguous and zero-filled in ascending order.

Sample (person_slug="sam-altman", interval="week", truncated):

## Episode timeseries — per week

**Range:** 2026-06-01 → 2026-06-29
**Total episodes:** 12
**Distinct podcasts:** 7

| Bucket | Episodes |
| --- | --- |
| 2026-06-01 | 8 |
| 2026-06-08 | 4 |

Example

Agent calls: particle_podcast_get_episode_timeseries {
  "keyword_search": "\"artificial general intelligence\"",
  "interval": "month",
  "published_after": "2026-01-01"
}

How often established finance experts were booked to talk about NVIDIA, per month:

Agent calls: particle_podcast_get_episode_timeseries {
  "company_slug": "nvidia",
  "guest_field": "banking-finance-and-investment",
  "guest_standing": "established",
  "interval": "month",
  "published_after": "2026-01-01"
}

Related

• REST equivalent: GET /v1/podcasts/episodes/timeseries.
• For how often a person, company or brand is mentioned, with ad reads left out and the shows carrying the mentions, use particle_podcast_get_mention_trends. This tool counts an episode for a company or entity named only in its ad reads, so for a brand that advertises heavily most of its count can be the brand’s own ads.
• To split the mentions themselves by the speakers’ occupations or fields, use particle_podcast_get_share_of_voice.
• For the underlying episodes, use particle_podcast_list_episodes; for the dialogue lines themselves, particle_podcast_find_mentions.