Get episode timeseries
Returns time-bucketed counts of episodes matching the same filters as GET /v1/podcasts/episodes, plus range totals. Use it for appearance, publication, or topic trend charts instead of paging the episode list or search once per period. keyword_search counts episodes whose transcripts match (exact counts, no pagination floors) and adds per-bucket mention_count plus total_mentions; semantic_search does the same by meaning, using the search endpoint's similarity threshold, and requires since. The two cannot be combined. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks. A since or until inside a bucket produces a partial first or last bucket labeled with the full bucket's start date. Requires at least one of entity_id, person_id, company_id, podcast_id, keyword_search, semantic_search, guest_occupation, or guest_field; the other guest_ filters narrow one of these. Omitting since aggregates all time, except with semantic_search, which always requires it. Ranges are capped at 1000 buckets.
Request
- Base URL: https://api.particle.pro
- URL: https://api.particle.pro/v1/podcasts/episodes/timeseries
- Auth: one of:
- API key in header X-API-Key
- HTTP bearer
Query parameters
Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID
Entity or person slug (e.g., 'elon-musk', 'openai') or ID. Counts episodes featuring this entity as a speaker or mentioned entity. A person with no linked entity counts the episodes they speak in. A slug that names both an entity and a person means the entity; pass the person's ID to count the person.
Person slug (e.g., 'dick-costolo'), knowledge-graph entity slug for the same person, or ID. Counts episodes featuring this person as a speaker. Works even when the speaker has no knowledge-graph entity linked. When the value itself matches a knowledge-graph entity slug (corroborated to the same person), the default and 'mention' roles also count episodes that merely mention the person, matching entity_id semantics; pass a speaker role (guest, host, panelist, correspondent) for speaker-only counts.
Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.
Entity role filter. Constrains which episodes match the entity_id, person_id, or company_id. 'speaker' matches any speaking role (host, co-host, guest, panelist, correspondent) without including mention-only episodes.
Keyword filter over episode transcript content. Double-quoted substrings must appear as exact phrases; unquoted terms must all appear in a transcript segment. Counts episodes with at least one matching segment and adds mention_count fields to the response. Combines with the other filters, but not with semantic_search.
Vector-similarity filter by meaning over episode transcript content — the counting twin of the search endpoint's semantic_search, using the same similarity threshold. Express the query the way you'd describe the topic to a colleague; paraphrase tolerant. Counts episodes with at least one semantically matching segment and adds mention_count fields to the response; for pathologically broad queries the mention counts can be lower bounds. Requires since (ranges up to ~2 years). Combines with the other filters, but not with keyword_search.
Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time.
End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now.
Deprecated alias of since.
Deprecated alias of until.
Bucket width. Weeks start on Monday and all buckets are UTC-aligned.
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'.
Only count episodes with completed transcripts
Only count episodes that have reached the terminal ingestion milestone
Minimum episode duration in seconds
Maximum episode duration in seconds
Only episodes with a guest listed under this SOC 2018 or ISCO-08 occupation (code, slug, or title), including a SOC group or everyday name such as physicians or doctors. A word with no occupation filters by the field of research or capacity it names: oncologists is field 3211, founders is guest_capacity=executive_founder.
Only episodes with a guest listed under this ANZSRC 2020 field of research (code, slug, or title).
Only episodes with a guest whose standing is recognized this way.
Only episodes with a guest at this seniority or above.
Only episodes with a guest who knows their field in this capacity, such as executive_founder for founders. It narrows the other filters; an everyday word for a capacity passed as guest_occupation (founders, politicians) lands here too.
Only episodes with a guest who still works in guest_occupation, a SOC 2018 occupation or group.
Only episodes with a guest speaking within their field (the guest the other guest_ filters select, when given).
Response
OK
Changes
No recorded changes to this operation across all 2 revisions of this API.