Get mention share of voice

Splits the podcast lines mentioning an entity by the occupations or fields of the people who said them: what share of what is said about it comes from, say, journalists or economists. A line counts when its speaker is linked to a person with an expertise reading and, for a guest, the appearance read does not doubt it is them; a person counts under every code listed for them, so shares can sum past 1. Ad reads are excluded unless include_ads. The window defaults to the last 30 days and may span 365; interval adds each group’s mentions per bucket. Requires entity_id or company_id. For the mentions themselves, use GET /v1/podcasts/mentions; for their counts over time, GET /v1/podcasts/mentions/timeseries.

GET /v1/podcasts/mentions/share-of-voice

cURL

cURL

curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/mentions/share-of-voice?by=occupation&level=major&speakers=all&limit=10"

200

{
  "attributed_mentions": 123,
  "by": "occupation",
  "end": "<string>",
  "groups": [
    {
      "code": "<string>",
      "episodes": 123,
      "mentions": 123,
      "share": 123,
      "speakers": 123,
      "title": "<string>",
      "buckets": [
        {
          "mentions": 123,
          "start": "<string>"
        }
      ]
    }
  ],
  "level": "major",
  "mentions": 123,
  "start": "<string>",
  "company": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "domain": "<string>",
    "image_url": "<string>",
    "slug": "<string>",
    "ticker": "<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>"
  },
  "keyword": "<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. One of entity_id, company_id, or keyword_search is required.

company_id · string

Company slug, domain, or ID. Resolves to the company's linked entity. One of entity_id, company_id, or keyword_search is required.

keyword_search · string

Split the lines that say these words instead of an entity's mentions: every word in one line, case-insensitive; wrap words in double quotes to require them adjacent and in order. Words are matched as spoken, so a word with two meanings counts both. The window may span at most 90 days, and a keyword said in more episodes than can be read is refused with a way to narrow it. One of entity_id, company_id, or keyword_search is required.

Maximum string length: 500

Example:

"\"weight loss\" drug"

by · enum<string> · default: occupation

Group the speakers by SOC 2018 occupation or ANZSRC 2020 field of research.

Available options: occupation, field

level · enum<string> · default: major

SOC major groups or detailed occupations; ANZSRC divisions or groups.

Available options: major, detailed

speakers · enum<string> · default: all

Attribute every speaker's lines, hosts included, or guests' and panelists' only.

Available options: all, guests

podcast_id · string

Restrict to mentions inside one podcast.

publisher_id · string

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

include_ads · boolean

Mentions inside ad reads are excluded by default. Pass true to include them.

since · string

Only episodes published on or after this date. Defaults to 30 days before until; the window may span at most 365 days, or 90 with keyword_search.

Example:

"2026-09-01"

until · string

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

Example:

"2026-10-01"

published_after · string · deprecated

Deprecated alias of since.

published_before · string · deprecated

Deprecated alias of until.

interval · enum<string>

Add each group's mentions per bucket of this width.

Available options: day, week, month

limit · integer<int64> · default: 10

Groups to return, most mentioned first.

Required range: 1 <= x <= 50

Response

200

application/json

OK

attributed_mentions · integer<int64> · required

Of those, the lines spoken by someone with an expertise reading (and, for a guest, whose appearance read does not doubt it is them). Shares are of these.

by · enum<string> · required

What the groups are: SOC 2018 occupations or ANZSRC 2020 fields of research.

Available options: occupation, field

end · string · required

Day the window ends (UTC), excluded: the window is [start, end), so a published_before date shows as the day after it.

groups · object[] | null · required

The groups with the most attributed mentions, most first. A person listed under several codes counts in each, so shares can sum past 1.

Show child attributes

level · enum<string> · required

The groups' level: SOC major groups or detailed occupations; ANZSRC divisions or groups.

Available options: major, detailed

mentions · integer<int64> · required

Lines mentioning the entity, or saying the keyword, in the window, from every speaker. Ad reads are left out unless include_ads.

start · string · required

First day of the window (UTC), included.

company · object

The company the entity was resolved from, when company_id was given.

Show child attributes

entity · object

The entity whose mentions are split.

Show child attributes

keyword · string

The keyword whose lines are split, when keyword_search was given instead of an entity. Mentions are then the lines that say it.