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 published_after. The two cannot be combined. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks. A published_after or published_before 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, or semantic_search. Omitting published_after 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
}

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 slug (e.g., 'elon-musk', 'openai') or ID. Counts episodes featuring this entity as a speaker or mentioned entity.

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 published_after (ranges up to ~2 years). Combines with the other filters, but not with keyword_search.

Maximum string length: 500

published_after · string

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

published_before · string

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

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

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.