---
title: "Brand against competitors"
method: GET
path: "/v1/analytics/share-of-voice"
tags: ["Analytics"]
---

# Brand against competitors

`GET /v1/analytics/share-of-voice`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/analytics/share-of-voice`
- Auth: HTTP bearer

Every keyword matched in the window with its counts and its share of brand plus competitor matches; topic keywords are counted but stay out of the split. The window is `range` (7d, 30d, 90d, 365d, ending today) or `from` and `to`, cut into days in `timezone` (UTC by default); `keywordIds` and `platforms` narrow it; `compare=true` adds the period of the same length right before it. Time axis is the publish date.

## Query parameters

- `range` '7d' | '30d' | '90d' | '365d': Preset window ending today. Ignored when from or to is given. Default 30d.
- `from` string: First day, YYYY-MM-DD, inclusive, in `timezone`.
- `to` string: Last day, YYYY-MM-DD, inclusive, in `timezone`. Default today.
- `keywordIds` string[], nullable: Only these keyword ids. Repeatable, or comma-separated; omit for every keyword.
- `platforms` string[]: Only these platforms. Repeatable, or comma-separated; omit for every platform.
- `compare` boolean: true adds the period of the same length right before the window as `previous`.
- `timezone` string: IANA zone the days are cut in (Europe/Madrid). Default UTC. One offset, the zone's at the end of the window, applies to the whole window.

## Response `200`

Keywords, most matched first

- ShareOfVoice
  - `window` object, required: The window the report covers.
    - `from` string, required: First day, inclusive.
    - `to` string, required: Last day, inclusive.
    - `days` integer, required: Length of the window in days.
    - `timezone` string, required: IANA zone the days were cut in.
  - `data` object[], required: Every keyword matched in the window, most matched first.
    - `keyword` object, required: The keyword this row is about.
      - `id` string, required: Keyword id (kw_...).
      - `term` string, required: The tracked term.
      - `kind` 'brand' | 'competitor' | 'topic', required: brand, competitor or topic.
      - `group` object, required: The group the keyword is in.
        - `id` string, required: Group id (grp_...).
        - `name` string, required: The group's name.
        - `externalId` string, nullable, required: Your own id for the group, or null.
        - `isDefault` boolean, required: The workspace's default group, where a keyword lands when no group is named.
    - `matched` integer, required: Matches of this keyword in the window.
    - `relevant` integer, required: Of those, scored at or above the relevance threshold.
    - `negative` integer, required: Of those, classified negative.
    - `buyIntent` integer, required: Of those, carrying the buy_intent intent.
    - `share` number, nullable, required: Percent of brand plus competitor matches, one decimal; null for topics, which stay out of the split.
    - `previous` object, nullable, required: The same keyword over the period right before the window; null unless compare=true.
      - `matched` integer, required: Matches of this keyword then.

## Other responses

- `400`: Invalid query
- `401`: Missing or invalid API key

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)