> ## Documentation Index > Fetch the complete documentation index at: https://docs.particle.pro/llms.txt > Use this file to discover all available pages before exploring further. # Compare how subjects are spoken of > Sets two to five entities' or companies' share of voice by one speaker statement characteristics axis side by side, over the same window, speakers and filter: how NVIDIA is spoken of next to AMD and Intel. Each subject is exactly the split GET /v1/podcasts/mentions/share-of-voice returns for it with by set to the axis: one group per label, each a share of the subject's scored_mentions and flagged low_sample below 20. Subjects are returned in the order given. A subject that matches nothing, or a company with no linked entity, is a 422 naming it. by defaults to sentiment; breakdown splits each label group by a second axis. For which professions say it, use the share of voice with by=occupation, one subject at a time. ## OpenAPI ````yaml /openapi.json get /v1/podcasts/mentions/share-of-voice/compare openapi: 3.1.0 info: contact: email: api@particle.pro name: Particle url: https://particle.pro description: >- Podcast API for transcripts, mentions and sponsorship data. 140,000+ podcasts transcribed, diarized and speaker-identified within minutes of airing, about 28,000 episodes a day. Search transcripts by keyword or meaning, track brand and company mentions with alerts, pull sponsor and ad-read data and rankings. REST API plus an MCP server for AI agents. Also company, people and topic intelligence. summary: >- Podcast API: transcripts, mentions, sponsors and rankings for 140,000+ podcasts. termsOfService: https://particle.pro/legal/tos-api title: Particle API version: 0.1.0 x-guidance: >- Podcast, people, company and topic intelligence. Authenticate with a pp_ API key (X-API-Key header) or pay per request with x402: a keyless call to a billable endpoint returns 402 with the payment requirements in the PAYMENT-REQUIRED header; sign the USDC transfer and repeat the request with PAYMENT-SIGNATURE. Start with GET /v1/podcasts/search?q=; the slugs in responses are the inputs to the other endpoints. Docs: https://docs.particle.pro; setup playbook: https://api.particle.pro/agents.md; endpoint and tool map with prices: https://api.particle.pro/llms.txt; credential recipe: https://api.particle.pro/auth.md. x-logo: url: https://particle.pro/favicon.svg servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] externalDocs: url: https://docs.particle.pro paths: /v1/podcasts/mentions/share-of-voice/compare: get: tags: - Podcast Episode Search - tier:standard summary: Compare how subjects are spoken of description: >- Sets two to five entities' or companies' share of voice by one speaker statement characteristics axis side by side, over the same window, speakers and filter: how NVIDIA is spoken of next to AMD and Intel. Each subject is exactly the split GET /v1/podcasts/mentions/share-of-voice returns for it with by set to the axis: one group per label, each a share of the subject's scored_mentions and flagged low_sample below 20. Subjects are returned in the order given. A subject that matches nothing, or a company with no linked entity, is a 422 naming it. by defaults to sentiment; breakdown splits each label group by a second axis. For which professions say it, use the share of voice with by=occupation, one subject at a time. operationId: compare-mentions-share-of-voice parameters: - description: >- Two to five entity slugs (e.g., 'sam-altman') or IDs, comma-separated, in the order to compare them. One of entity_id or company_id is required. explode: false in: query name: entity_id schema: description: >- Two to five entity slugs (e.g., 'sam-altman') or IDs, comma-separated, in the order to compare them. One of entity_id or company_id is required. examples: - - sam-altman - dario-amodei items: type: string type: - array - 'null' - description: >- Two to five company slugs, domains, or IDs, comma-separated, in the order to compare them. Each resolves to the company's linked entity. One of entity_id or company_id is required. explode: false in: query name: company_id schema: description: >- Two to five company slugs, domains, or IDs, comma-separated, in the order to compare them. Each resolves to the company's linked entity. One of entity_id or company_id is required. examples: - - nvidia - amd - intel items: type: string type: - array - 'null' - description: >- Not accepted: speaker statement characteristics are read on an entity's or a company's mentions, not on the lines that say a keyword, so passing it returns 422. explode: false in: query name: keyword_search schema: description: >- Not accepted: speaker statement characteristics are read on an entity's or a company's mentions, not on the lines that say a keyword, so passing it returns 422. maxLength: 500 type: string - description: >- The speaker statement characteristics axis whose labels each subject's lines are grouped by: by=sentiment is how negatively or positively each subject was spoken of. explode: false in: query name: by schema: default: sentiment description: >- The speaker statement characteristics axis whose labels each subject's lines are grouped by: by=sentiment is how negatively or positively each subject was spoken of. enum: - sentiment - certainty - specificity - temporal_orientation type: string - description: >- Attribute every speaker's lines, hosts included, or guests' and panelists' only. explode: false in: query name: speakers schema: default: all description: >- Attribute every speaker's lines, hosts included, or guests' and panelists' only. enum: - all - guests type: string - description: Restrict to mentions inside one podcast. explode: false in: query name: podcast_id schema: description: Restrict to mentions inside one podcast. type: string - description: >- Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID. explode: false in: query name: publisher_id schema: description: >- Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID. type: string - description: >- Mentions inside ad reads are excluded by default. Pass true to include them. explode: false in: query name: include_ads schema: description: >- Mentions inside ad reads are excluded by default. Pass true to include them. type: boolean - description: >- Only episodes published on or after this date. Defaults to 30 days before until; the window may span at most 365 days. explode: false in: query name: since schema: description: >- Only episodes published on or after this date. Defaults to 30 days before until; the window may span at most 365 days. examples: - '2026-09-01' type: string - description: Only episodes published on or before this date. Defaults to now. explode: false in: query name: until schema: description: Only episodes published on or before this date. Defaults to now. examples: - '2026-10-01' type: string - deprecated: true description: Deprecated alias of since. explode: false in: query name: published_after schema: deprecated: true description: Deprecated alias of since. type: string - deprecated: true description: Deprecated alias of until. explode: false in: query name: published_before schema: deprecated: true description: Deprecated alias of until. type: string - description: >- Also split each label group's lines by their label on this second axis: by=temporal_orientation&breakdown=certainty is how sure each subject's predictions are. Must differ from by. explode: false in: query name: breakdown schema: description: >- Also split each label group's lines by their label on this second axis: by=temporal_orientation&breakdown=certainty is how sure each subject's predictions are. Must differ from by. enum: - sentiment - certainty - specificity - temporal_orientation type: string - description: >- Count only mentions said a certain way, for every subject: speaker_statement_characteristics[temporal_orientation]=future compares how each subject's predictions lean. 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. explode: true in: query name: speaker_statement_characteristics schema: description: >- Count only mentions said a certain way, for every subject: speaker_statement_characteristics[temporal_orientation]=future compares how each subject's predictions lean. 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. properties: certainty: description: >- The certainty labels to keep: hedged, neutral, confident. Comma-separate labels to accept any of them (hedged,confident); repeating the key accepts any of its values too. examples: - confident - hedged,confident type: string sentiment: description: >- The sentiment labels to keep: negative, neutral, positive. Comma-separate labels to accept any of them (negative,positive); repeating the key accepts any of its values too. examples: - positive - negative,positive type: string specificity: description: >- The specificity labels to keep: vague, neutral, specific. Comma-separate labels to accept any of them (vague,specific); repeating the key accepts any of its values too. examples: - specific - vague,specific type: string temporal_orientation: description: >- The temporal_orientation labels to keep: past, present, future. Comma-separate labels to accept any of them (past,future); repeating the key accepts any of its values too. examples: - future - past,future type: string type: object style: deepObject responses: '200': content: application/json: schema: $ref: '#/components/schemas/ShareOfVoiceComparison' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: Error x-codeSamples: - label: cURL lang: curl source: |- curl -H "X-API-Key: $PARTICLE_API_KEY" \ "https://api.particle.pro/v1/podcasts/mentions/share-of-voice/compare?by=sentiment&speakers=all" components: schemas: ShareOfVoiceComparison: additionalProperties: false properties: breakdown: description: >- The axis each label group's lines are split by, when breakdown was given. enum: - sentiment - certainty - specificity - temporal_orientation type: string by: description: >- The speaker statement characteristics axis whose labels every subject's groups are. enum: - sentiment - certainty - specificity - temporal_orientation type: string characteristics_version: description: >- Opaque version of the speaker statement characteristics every subject read. Absent when no subject read any, or when they read different versions: compare subjects only when it is present. type: string end: description: 'Day the window ends (UTC), excluded: the window is [start, end).' type: string speakers: description: >- Whose lines every subject's groups count: every speaker's, or guests' and panelists' only. enum: - all - guests type: string start: description: First day of the window (UTC), included. type: string subjects: description: >- One split per subject, in the order requested, each exactly what GET /v1/podcasts/mentions/share-of-voice returns for that subject with the same parameters. items: $ref: '#/components/schemas/ShareOfVoice' type: - array - 'null' required: - by - start - end - speakers - subjects type: object PlatformError: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string error_code: type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string resolve: $ref: '#/components/schemas/ErrorResolve' status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object ShareOfVoice: additionalProperties: false properties: attributed_mentions: description: >- Of speaker_mentions, the lines spoken by someone with an expertise reading (and, for a guest, whose appearance read does not doubt it is them). Shares of occupations and fields are of these. format: int64 type: integer breakdown: description: The axis each group's lines are split by, when breakdown was given. enum: - sentiment - certainty - specificity - temporal_orientation type: string by: description: >- What the groups are: SOC 2018 occupations, ANZSRC 2020 fields of research, or the labels of one speaker statement characteristics axis. enum: - occupation - field - sentiment - certainty - specificity - temporal_orientation type: string characteristics_version: description: >- Opaque version of the speaker statement characteristics the split read. Compare splits only when it is equal. type: string company: $ref: '#/components/schemas/CompanyCompact' description: The company the entity was resolved from, when company_id was given. end: description: >- Day the window ends (UTC), excluded: the window is [start, end), so a published_before date shows as the day after it. type: string entity: $ref: '#/components/schemas/EntityCompact' description: The entity whose mentions are split. groups: description: >- By occupation or field, the groups with the most attributed mentions, most first; a person listed under several codes counts in each, so shares can sum past 1. By an axis, one group per label in the axis's order, zero counts included. items: $ref: '#/components/schemas/ShareOfVoiceGroup' type: - array - 'null' host_mentions: description: Of mentions, the lines hosts spoke, counted whatever speakers is. format: int64 type: integer keyword: description: >- The keyword whose lines are split, when keyword_search was given instead of an entity. Mentions are then the lines that say it. type: string level: description: >- The groups' level: SOC major groups or detailed occupations; ANZSRC divisions or groups. Absent when by is an axis. enum: - major - detailed type: string mentions: description: >- Lines mentioning the entity, or saying the keyword, in the window, from every speaker. Ad reads are left out unless include_ads. format: int64 type: integer scored_mentions: description: >- The lines the groups count that carry speaker statement characteristics, when by is an axis, breakdown is set or speaker_statement_characteristics filters: shares of an axis's labels are of these. Not every line carries them, so this can be below the lines counted. format: int64 type: integer speaker_mentions: description: >- Of those, the lines spoken by the speakers counted: all of them, or guests' and panelists' with speakers=guests. Coverage is attributed_mentions over this. format: int64 type: integer speakers: description: >- Whose lines the groups count: every speaker's, or guests' and panelists' only. enum: - all - guests type: string start: description: First day of the window (UTC), included. type: string required: - by - start - end - speakers - mentions - speaker_mentions - host_mentions - attributed_mentions - groups type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ErrorResolve: additionalProperties: false properties: action: type: string endpoint: type: string message: type: string method: type: string url: type: string required: - message type: object CompanyCompact: additionalProperties: false properties: description: description: Short company description, when known. type: string domain: description: Primary website domain (e.g. 'nvidia.com'), when known. type: string id: description: Company identifier (domain, slug, or encoded ID) type: string image_url: description: Company logo or image URL type: string name: description: Company name type: string slug: description: >- Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Companies have no slug of their own; prefer this for display and pass it (or id) to /v1/companies. type: string ticker: description: Primary stock ticker symbol, when listed. type: string required: - id - name type: object EntityCompact: additionalProperties: false properties: company: $ref: '#/components/schemas/EntityCompany' description: Linked company record, if this entity is a known company description: description: Short description type: string id: description: Entity ID type: string image_url: description: Entity image URL type: string name: description: Entity name type: string person: $ref: '#/components/schemas/EntityPerson' description: Linked person record, if this entity is a known person slug: description: Human-readable slug identifier type: string type: $ref: '#/components/schemas/EntityType' description: Category. Omitted when the entity falls outside the supported set. wikipedia_url: description: Wikipedia URL type: string required: - id - slug - name type: object ShareOfVoiceGroup: additionalProperties: false properties: breakdown: description: >- With breakdown, the group's scored mentions by their label on that axis, one entry per label in the axis's order. items: $ref: '#/components/schemas/ShareOfVoiceLabel' type: - array - 'null' buckets: description: The group's mentions per interval bucket, when interval is set. items: $ref: '#/components/schemas/ShareOfVoiceBucket' type: - array - 'null' code: description: >- The SOC 2018 or ANZSRC 2020 code, or, when by is an axis, the label (e.g. negative). type: string episodes: description: Distinct episodes they were said in. format: int64 type: integer examples: description: >- With examples and no breakdown, up to that many of the group's lines, strongest first: by an axis, the lines that most clearly carry the group's label; filtered by speaker_statement_characteristics, those that most clearly read the way the filter asks; otherwise the newest. Ties go to the newest. With breakdown, each breakdown label carries its own instead. items: $ref: '#/components/schemas/ShareOfVoiceExample' type: - array - 'null' low_sample: description: >- Fewer than 20 scored mentions stand behind the group's label shares: its breakdown's with breakdown, or the split's when by is an axis. Read them as examples, not as a distribution. type: boolean mentions: description: >- Lines mentioning the entity or saying the keyword in this group. By occupation or field: attributed lines spoken by people listed under the code. By an axis: scored lines carrying the label, spoken by the speakers counted, whether or not the speaker has an expertise reading. format: int64 type: integer scored_mentions: description: >- With breakdown, the group's mentions that carry speaker statement characteristics: its breakdown's shares are of these. format: int64 type: integer share: description: >- mentions over attributed_mentions by occupation or field, or over scored_mentions when by is an axis (0-1). format: double type: number speakers: description: Distinct people who said them. format: int64 type: integer title: description: The code's title, or the label again when by is an axis. type: string top: $ref: '#/components/schemas/ShareOfVoiceTop' description: >- At level=detailed, the top-level group the code sits under (a SOC major group or an ANZSRC division) and its share, so a group split across detailed codes still shows its size. required: - code - title - mentions - share - speakers - episodes type: object EntityCompany: additionalProperties: false properties: domain: description: Company website domain type: string id: description: Company identifier type: string ticker: description: Primary stock ticker symbol type: string required: - id type: object EntityPerson: additionalProperties: false properties: company: description: Current company name type: string id: description: Person identifier type: string image_url: description: Person headshot URL type: string title: description: Current role title type: string required: - id type: object EntityType: additionalProperties: false properties: name: description: Human-friendly display label (e.g. 'Company'). type: string slug: description: >- Stable identifier, safe to pass to the type query parameter (e.g. 'company'). type: string required: - slug - name type: object ShareOfVoiceLabel: additionalProperties: false properties: examples: description: >- With examples, up to that many of the group's lines with this label, strongest first: the lines that most clearly carry it. Ties go to the newest. items: $ref: '#/components/schemas/ShareOfVoiceExample' type: - array - 'null' label: description: The label on the breakdown axis. type: string mentions: description: The scored mentions with the label, of the group or bucket it is in. format: int64 type: integer share: description: >- mentions over the scored_mentions of the group or bucket it is in (0-1). format: double type: number required: - label - mentions - share type: object ShareOfVoiceBucket: additionalProperties: false properties: mentions: format: int64 type: integer start: description: First day of the bucket (UTC). type: string required: - start - mentions type: object ShareOfVoiceExample: additionalProperties: false properties: episode: $ref: '#/components/schemas/EpisodeCompactWithPodcast' description: Episode the line was said in. line: $ref: '#/components/schemas/TranscriptLine' description: >- The line: its text, speaker and times, with is_mention set and its speaker_statement_characteristics when it has been read. person: $ref: '#/components/schemas/PersonCompact' description: The person who said it. start_seconds: description: When the line starts, in seconds (episode-absolute). format: double type: number url: description: >- Moment link that plays the line on Radar: the episode's web_url with ?t= at start_seconds. type: string required: - episode - start_seconds - line type: object ShareOfVoiceTop: additionalProperties: false properties: code: description: The SOC 2018 major group or ANZSRC 2020 division. type: string share: description: The top-level group's mentions over attributed_mentions (0-1). format: double type: number title: description: The code's title. type: string required: - code - title - share type: object EpisodeCompactWithPodcast: additionalProperties: false properties: id: description: Episode ID type: string podcast: $ref: '#/components/schemas/PodcastCompact' description: Parent podcast published_at: description: Publication date format: date-time type: string slug: description: Human-readable slug identifier type: string title: description: Episode title type: string web_url: description: >- The episode's page on Radar, where it plays beside its transcript: https://radar.particle.pro/podcasts/{podcast}/episodes/{episode}, each segment the slug or, when there is none, the raw UUID. Append ?t={seconds} to start at a moment; the hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch the episode. type: string required: - id - title type: object TranscriptLine: additionalProperties: false properties: end_seconds: description: End time in seconds (episode-absolute) format: double type: number is_match: description: >- Top-scored line within the window for the current query, on /v1/podcasts/episodes/search results. Not set on /v1/podcasts/mentions. type: boolean is_mention: description: >- Line contains a textual mention of the resolved entity. Set on /v1/podcasts/mentions only — /v1/podcasts/episodes/search treats entity_id as a filter and does not mark mention lines. type: boolean matched_terms: description: >- Terms from the query that occur in this line, longest-first, for clients to highlight. Locate them case-insensitively: each term is spelled as the query spelled it, which may differ in case from the line's text (query "openai" is reported for a line reading "OpenAI"). Whole-token matches only — a term never matches inside a longer word, so "AI" is not reported for "said". A multi-word query yields the whole phrase ("founder mode") when it occurs contiguously, so clients mark it as one span rather than highlighting each word separately; individual words appear only where they occur outside the phrase. Only the longest term is reported at any position, so terms never overlap. On /v1/podcasts/episodes/search this is set on any line in the window containing the query, not only is_match lines; on /v1/podcasts/mentions it is set only on is_mention lines. Absent when nothing matched or the query was not text-based. items: type: string type: - array - 'null' number: description: Line number within the episode (1-indexed) format: int64 type: integer role: description: Speaker role (HOST, GUEST, etc.) type: string segment_id: description: >- The segment containing this line. Set on is_mention lines of /v1/podcasts/mentions, so a mention can be cited by segment even when its window opened in the previous one (a window starts context_lines before its first mention, and the window's segment is where the window starts). Absent elsewhere. type: string speaker: description: Speaker name or label type: string speaker_statement_characteristics: $ref: '#/components/schemas/SpeakerStatementCharacteristics' description: >- How the speaker said this line: its sentiment, certainty, specificity and temporal orientation, as labels. A pole label (such as positive or confident) means the line clearly reads that way; a borderline line takes the middle label. Set on lines of /v1/podcasts/episodes/search and /v1/podcasts/mentions windows when the line has been read. Absent on lines that are not: short lines, and lines in intros, ad breaks and other segments outside topic discussions and interviews. start_seconds: description: Start time in seconds (episode-absolute) format: double type: number text: description: Spoken text type: string required: - number - speaker - start_seconds - end_seconds - text type: object PersonCompact: additionalProperties: false properties: description: description: Short description (e.g. current role), when known. type: string id: description: Encoded Person identifier type: string image_url: description: Canonical headshot URL when one is known for the Person type: string name: description: Display name type: string slug: description: >- Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. type: string required: - id - name type: object PodcastCompact: additionalProperties: false properties: best_rank: $ref: '#/components/schemas/PodcastRankingHandle' description: >- The single best (lowest-numbered) chart position this podcast currently holds across all charts. Omitted when the podcast holds no current chart appearances, and on endpoints that do not attach it. Reading a full chart (with country/category/source filters and history) remains premium; a single show's own placement is available on every plan. id: description: Podcast ID type: string image_url: description: Cover image URL type: string popularity: description: >- Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. format: double type: number publisher: $ref: '#/components/schemas/PodcastPublisherCompact' description: >- Publisher (network) attributed to this podcast. Present only when the embedding endpoint preloads publisher attribution and the podcast's publisher is known. slug: description: Human-readable slug identifier type: string title: description: Podcast title type: string required: - id - title type: object SpeakerStatementCharacteristics: additionalProperties: false properties: certainty: description: >- How sure the speaker sounds: hedged ("maybe", "I think", "it could"), neutral, or confident (flat assertion). enum: - hedged - neutral - confident type: string sentiment: description: 'The statement''s tone: negative, neutral or positive.' enum: - negative - neutral - positive type: string specificity: description: >- Whether the line commits to something concrete: specific (names, numbers, dates, mechanisms), neutral, or vague (generalities). enum: - vague - neutral - specific type: string temporal_orientation: description: >- Where the line points in time: past (looking back), present (how things are), or future (predictions, plans, expectations). enum: - past - present - future type: string required: - sentiment - certainty - specificity - temporal_orientation type: object PodcastRankingHandle: additionalProperties: false properties: captured_at: format: date-time type: string category_slug: type: string chart_type: enum: - top_podcasts type: string country: type: string rank: format: int64 type: integer source: enum: - apple - spotify type: string required: - source - chart_type - rank - captured_at type: object PodcastPublisherCompact: additionalProperties: false properties: id: description: Publisher ID type: string name: description: Publisher name type: string slug: description: >- Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). type: string required: - id - name type: object securitySchemes: ApiKeyHeader: description: Pass your API key in the X-API-Key header (recommended). in: header name: X-API-Key type: apiKey BearerAuth: description: Pass your API key as a Bearer token in the Authorization header. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.