curl -H "X-API-Key: $PARTICLE_API_KEY" \
"https://api.particle.pro/v1/podcasts/mentions/timeseries?interval=week"{
"buckets": [
{
"episode_count": 123,
"mention_count": 123,
"podcast_count": 123,
"start": "<string>",
"breakdown": [
{
"label": "<string>",
"mentions": 123,
"share": 123,
"examples": [
{
"episode": {
"id": "<string>",
"title": "<string>",
"podcast": {
"id": "<string>",
"title": "<string>",
"best_rank": {
"captured_at": "2023-11-07T05:31:56Z",
"chart_type": "top_podcasts",
"rank": 123,
"source": "apple",
"category_slug": "<string>",
"country": "<string>"
},
"image_url": "<string>",
"popularity": 123,
"publisher": {
"id": "<string>",
"name": "<string>",
"slug": "<string>"
},
"slug": "<string>"
},
"published_at": "2023-11-07T05:31:56Z",
"slug": "<string>",
"web_url": "<string>"
},
"line": {
"end_seconds": 123,
"number": 123,
"speaker": "<string>",
"start_seconds": 123,
"text": "<string>",
"is_match": true,
"is_mention": true,
"matched_terms": [
"<string>"
],
"role": "<string>",
"segment_id": "<string>",
"speaker_statement_characteristics": {
"certainty": "hedged",
"sentiment": "negative",
"specificity": "vague",
"temporal_orientation": "past"
}
},
"start_seconds": 123,
"person": {
"id": "<string>",
"name": "<string>",
"description": "<string>",
"image_url": "<string>",
"slug": "<string>"
},
"url": "<string>"
}
]
}
],
"low_sample": true,
"partial": true,
"scored_mentions": 123
}
],
"distinct_podcasts": 123,
"interval": "day",
"total_episodes": 123,
"total_mentions": 123,
"breakdown": "sentiment",
"characteristics_version": "<string>",
"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>"
},
"scored_mentions": 123,
"start": "<string>"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}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.
curl -H "X-API-Key: $PARTICLE_API_KEY" \
"https://api.particle.pro/v1/podcasts/mentions/timeseries?interval=week"{
"buckets": [
{
"episode_count": 123,
"mention_count": 123,
"podcast_count": 123,
"start": "<string>",
"breakdown": [
{
"label": "<string>",
"mentions": 123,
"share": 123,
"examples": [
{
"episode": {
"id": "<string>",
"title": "<string>",
"podcast": {
"id": "<string>",
"title": "<string>",
"best_rank": {
"captured_at": "2023-11-07T05:31:56Z",
"chart_type": "top_podcasts",
"rank": 123,
"source": "apple",
"category_slug": "<string>",
"country": "<string>"
},
"image_url": "<string>",
"popularity": 123,
"publisher": {
"id": "<string>",
"name": "<string>",
"slug": "<string>"
},
"slug": "<string>"
},
"published_at": "2023-11-07T05:31:56Z",
"slug": "<string>",
"web_url": "<string>"
},
"line": {
"end_seconds": 123,
"number": 123,
"speaker": "<string>",
"start_seconds": 123,
"text": "<string>",
"is_match": true,
"is_mention": true,
"matched_terms": [
"<string>"
],
"role": "<string>",
"segment_id": "<string>",
"speaker_statement_characteristics": {
"certainty": "hedged",
"sentiment": "negative",
"specificity": "vague",
"temporal_orientation": "past"
}
},
"start_seconds": 123,
"person": {
"id": "<string>",
"name": "<string>",
"description": "<string>",
"image_url": "<string>",
"slug": "<string>"
},
"url": "<string>"
}
]
}
],
"low_sample": true,
"partial": true,
"scored_mentions": 123
}
],
"distinct_podcasts": 123,
"interval": "day",
"total_episodes": 123,
"total_mentions": 123,
"breakdown": "sentiment",
"characteristics_version": "<string>",
"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>"
},
"scored_mentions": 123,
"start": "<string>"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Authorizations
Pass your API key in the X-API-Key header (recommended).
Query Parameters
Entity slug (e.g., 'sam-altman') or ID. Required when company_id is not set.
Company slug, domain, or ID. Required when entity_id is not set. Resolves to the company's linked entity.
Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.
Constrain how the entity participates: guest, host, panelist, correspondent, or mention.
guest, host, panelist, correspondent, mention Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them.
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'.
"fr"
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.
200Only mentions spoken by a guest listed under this ANZSRC 2020 field of research (code, slug, or title).
200Only mentions spoken by a guest whose standing is recognized this way.
established, self_described, unverified Only mentions spoken by a guest at this seniority or above.
professional, senior, distinguished 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.
researcher, licensed_professional, practitioner, executive_founder, public_official, journalist_analyst, creator_entertainer, athlete_coach, clergy, firsthand, layperson Only mentions spoken by a guest who still works in guest_occupation, a SOC 2018 occupation or group.
Only mentions spoken by a guest speaking within their field (the guest the other guest_ filters select, when given).
Restrict to mentions inside one podcast.
Only episodes published on or after this date. Omit to aggregate all time.
"2026-01-01"
Only episodes published on or before this date. Defaults to now.
"2026-06-01"
Deprecated alias of since.
Deprecated alias of until.
Bucket width.
day, week, month Also split each bucket's mentions by their label on this speaker statement characteristics axis: breakdown=sentiment is whether the subject is spoken of more negatively over time. Each bucket's label shares are of its scored_mentions, the mentions that carry the labels, and a bucket with fewer than 20 is low_sample. Mention counts are unchanged. Requires since, and the range may span at most 365 days.
sentiment, certainty, specificity, temporal_orientation Count only mentions said a certain way: speaker_statement_characteristics[temporal_orientation]=future charts predictions about the subject over time. Each key is an axis (sentiment, certainty, specificity, temporal_orientation) and its value one or more of that axis's labels, comma-separated: labels on one axis match any of them, and axes combine with AND. An episode counts only when one of its mentions is said that way, and lines without the labels are not counted. Requires since, and the range may span at most 365 days.
Show child attributes
Show child attributes
Response
OK
Contiguous zero-filled buckets in ascending order
Show child attributes
Show child attributes
Distinct podcasts those episodes aired on
Bucket width
day, week, month Episodes with at least one counted mention in the range
Counted mention lines across those episodes
The axis each bucket's mentions are split by, when breakdown was given.
sentiment, certainty, specificity, temporal_orientation Opaque version of the speaker statement characteristics the series read. Compare series only when it is equal. Absent when no line was read: a subject without a linked entity, or a podcast or publisher with no shows.
The resolved company, when company_id was used
Show child attributes
Show child attributes
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.
The resolved entity the counts are for
Show child attributes
Show child attributes
With breakdown or speaker_statement_characteristics, the mentions in the range that carry speaker statement characteristics. They are read from each mention line, while mention counts without speaker_statement_characteristics are the episodes' stored counts, so the two can differ slightly either way.
Start of the first bucket as a UTC date
Was this page helpful?