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

cURL

cURL

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

200

{
  "buckets": [
    {
      "episode_count": 123,
      "mention_count": 123,
      "podcast_count": 123,
      "start": "<string>",
      "partial": true
    }
  ],
  "distinct_podcasts": 123,
  "interval": "day",
  "total_episodes": 123,
  "total_mentions": 123,
  "company": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "domain": "<string>",
    "image_url": "<string>",
    "slug": "<string>",
    "ticker": "<string>"
  },
  "end": "<string>",
  "entity": {
    "id": "<string>",
    "name": "<string>",
    "slug": "<string>",
    "company": {
      "id": "<string>",
      "domain": "<string>",
      "ticker": "<string>"
    },
    "description": "<string>",
    "image_url": "<string>",
    "person": {
      "id": "<string>",
      "company": "<string>",
      "image_url": "<string>",
      "title": "<string>"
    },
    "type": {
      "name": "<string>",
      "slug": "<string>"
    },
    "wikipedia_url": "<string>"
  },
  "start": "<string>"
}

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

entity_id · string

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

company_id · string

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

publisher_id · string

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

role · enum<string>

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

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

include_ads · boolean

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

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"

guest_occupation · string

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.

Maximum string length: 200

guest_field · string

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

Maximum string length: 200

guest_standing · enum<string>

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

Available options: established, self_described, unverified

guest_seniority · enum<string>

Only mentions spoken by a guest at this seniority or above.

Available options: professional, senior, distinguished

guest_capacity · enum<string>

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.

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

guest_practicing · boolean

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

guest_in_field · boolean

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

podcast_id · string

Restrict to mentions inside one podcast.

since · string

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

Example:

"2026-01-01"

until · string

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

Example:

"2026-06-01"

published_after · string · deprecated

Deprecated alias of since.

published_before · string · deprecated

Deprecated alias of until.

interval · enum<string> · default: week

Bucket width.

Available options: day, week, month

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 aired on

interval · enum<string> · required

Bucket width

Available options: day, week, month

total_episodes · integer<int64> · required

Episodes with at least one counted mention in the range

total_mentions · integer<int64> · required

Counted mention lines across those episodes

company · object

The resolved company, when company_id was used

Show child attributes

end · string

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.

entity · object

The resolved entity the counts are for

Show child attributes

start · string

Start of the first bucket as a UTC date