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.

GET /v1/podcasts/episodes/timeseries

cURL

cURL

curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/episodes/timeseries?interval=week"

200

{
  "buckets": [
    {
      "count": 123,
      "start": "<string>",
      "mention_count": 123
    }
  ],
  "distinct_podcasts": 123,
  "interval": "day",
  "total_episodes": 123,
  "end": "<string>",
  "start": "<string>",
  "total_mentions": 123
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Query Parameters

podcast_id · string

Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID

entity_id · string

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_id · string

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_id · string

Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.

role · enum<string>

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.

Available options: guest, host, panelist, correspondent, speaker, mention

keyword_search · string

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.

Maximum string length: 500

semantic_search · string

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.

Maximum string length: 500

since · string

Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time.

until · string

End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now.

published_after · string · deprecated

Deprecated alias of since.

published_before · string · deprecated

Deprecated alias of until.

interval · enum<string> · default: week

Bucket width. Weeks start on Monday and all buckets are UTC-aligned.

Available options: day, week, month

language · string

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'.

Example:

"fr"

has_transcript · boolean

Only count episodes with completed transcripts

fully_ingested · boolean

Only count episodes that have reached the terminal ingestion milestone

min_duration · integer<int64>

Minimum episode duration in seconds

Required range: 0 <= x <= 9223372036

max_duration · integer<int64>

Maximum episode duration in seconds

Required range: 0 <= x <= 9223372036

guest_occupation · string

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.

Maximum string length: 200

guest_field · string

Only episodes with a guest listed under this ANZSRC 2020 field of research (code, slug, or title).

Maximum string length: 200

guest_standing · enum<string>

Only episodes with a guest whose standing is recognized this way.

Available options: established, self_described, unverified

guest_seniority · enum<string>

Only episodes with a guest at this seniority or above.

Available options: professional, senior, distinguished

guest_capacity · enum<string>

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.

Available options: researcher, licensed_professional, practitioner, executive_founder, public_official, journalist_analyst, creator_entertainer, athlete_coach, clergy, firsthand, layperson

guest_practicing · boolean

Only episodes with a guest who still works in guest_occupation, a SOC 2018 occupation or group.

guest_in_field · boolean

Only episodes with a guest speaking within their field (the guest the other guest_ filters select, when given).

Response

200

application/json

OK

buckets · object[] | null · required

Contiguous zero-filled buckets in ascending order

Show child attributes

distinct_podcasts · integer<int64> · required

Distinct podcasts those episodes belong to

interval · enum<string> · required

Bucket width

Available options: day, week, month

total_episodes · integer<int64> · required

Distinct episodes matching the filters in the range

end · string

UTC date of the range's exclusive upper bound. When the bound falls inside a day, such as the default of now, episodes on this date up to the bound are still counted.

start · string

Start of the first bucket as a UTC date

total_mentions · integer<int64>

Transcript segments matching keyword_search or semantic_search across the range. Present only when one of them is set.