Podcast Episode Search
tier:standard

Get mention timeseries

Returns time-bucketed counts of episodes mentioning an entity, plus per-bucket mention line and distinct podcast counts and range totals — the aggregate twin of /v1/podcasts/mentions. For windows the search can fully enumerate, bucket counts match what it returns: mentions inside ad reads are excluded by default (pass include_ads=true to count them), so use this for mention trend charts instead of paging the search once per period. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks; a bucket the window cuts through, such as the current week of a window running to now, is marked partial, so compare full buckets with each other. Requires entity_id or company_id. Omitting since aggregates all time. Ranges are capped at 1000 buckets.

For which podcasts carried the mentions, compared with the period before, use /v1/podcasts/mentions/by-podcast. For appearance trends by speaker role across episode-level filters (language, duration, keyword_search) use /v1/podcasts/episodes/timeseries instead; its role=mention counts include ad reads.

get/v1/podcasts/mentions/timeseries

Request

  • Base URL: https://api.particle.pro
  • URL: https://api.particle.pro/v1/podcasts/mentions/timeseries
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Query parameters

entity_idstring

Entity slug (e.g., 'sam-altman') or ID. Required when company_id is not set.

company_idstring

Company slug, domain, or ID. Required when entity_id is not set. Resolves to the company's linked entity.

publisher_idstring

Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.

role'guest' | 'host' | 'panelist' | 'correspondent' | 'mention'

Constrain how the entity participates: guest, host, panelist, correspondent, or mention.

include_adsboolean

Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them.

languagestring

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
guest_occupationstring

Only mentions spoken by 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_fieldstring

Only mentions spoken by a guest listed under this ANZSRC 2020 field of research (code, slug, or title).

guest_standing'established' | 'self_described' | 'unverified'

Only mentions spoken by a guest whose standing is recognized this way.

guest_seniority'professional' | 'senior' | 'distinguished'

Only mentions spoken by 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 mentions spoken by 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_practicingboolean

Only mentions spoken by a guest who still works in guest_occupation, a SOC 2018 occupation or group.

guest_in_fieldboolean

Only mentions spoken by a guest speaking within their field (the guest the other guest_ filters select, when given).

podcast_idstring

Restrict to mentions inside one podcast.

sincestring

Only episodes published on or after this date. Omit to aggregate all time.

Example:2026-01-01
untilstring

Only episodes published on or before this date. Defaults to now.

Example:2026-06-01
published_afterstring

Deprecated alias of since.

published_beforestring

Deprecated alias of until.

interval'day' | 'week' | 'month'

Bucket width.

Response

OK

distinct_podcastsinteger required

Distinct podcasts those episodes aired on

endstring

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

interval'day' | 'week' | 'month' required

Bucket width

startstring

Start of the first bucket as a UTC date

total_episodesinteger required

Episodes with at least one counted mention in the range

total_mentionsinteger required

Counted mention lines across those episodes

Changes

No recorded changes to this operation across all 2 revisions of this API.