---
title: "Get episode timeseries"
method: GET
path: "/v1/podcasts/episodes/timeseries"
tags: ["Podcast Episodes", "tier:standard"]
---

# Get episode timeseries

`GET /v1/podcasts/episodes/timeseries`

## 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

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.

## 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` 'guest' | 'host' | 'panelist' | 'correspondent' | 'speaker' | 'mention': 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_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.
- `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.
- `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 alias of since.
- `published_before` string: Deprecated alias of until.
- `interval` 'day' | 'week' | 'month': Bucket width. Weeks start on Monday and all buckets are UTC-aligned.
- `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'.
- `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: Minimum episode duration in seconds
- `max_duration` integer: Maximum episode duration in seconds
- `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.
- `guest_field` string: Only episodes with a guest listed under this ANZSRC 2020 field of research (code, slug, or title).
- `guest_standing` 'established' | 'self_described' | 'unverified': Only episodes with a guest whose standing is recognized this way.
- `guest_seniority` 'professional' | 'senior' | 'distinguished': Only episodes with a guest at this seniority or above.
- `guest_capacity` 'researcher' | 'licensed_professional' | 'practitioner' | 'executive_founder' | 'public_official' | 'journalist_analyst' | 'creator_entertainer' | 'athlete_coach' | 'clergy' | 'firsthand' | 'layperson': 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.
- `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`

OK

- EpisodeTimeseries
  - `buckets` EpisodeTimeseriesBucket[], nullable, required: Contiguous zero-filled buckets in ascending order
    - `count` integer, required: Distinct episodes matching the filters in this bucket
    - `mention_count` integer: Transcript segments matching keyword_search or semantic_search in this bucket. Present only when one of them is set.
    - `start` string, required: Bucket start as a UTC date
  - `distinct_podcasts` integer, required: Distinct podcasts those episodes belong to
  - `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.
  - `interval` 'day' | 'week' | 'month', required: Bucket width
  - `start` string: Start of the first bucket as a UTC date
  - `total_episodes` integer, required: Distinct episodes matching the filters in the range
  - `total_mentions` integer: Transcript segments matching keyword_search or semantic_search across the range. Present only when one of them is set.

## Other responses

- `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent.
- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)