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

# Get share of voice

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

## Request

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

Returns each keyword with matches in the period, its counts and its share of all brand and competitor matches. Topic keywords are counted but not part of the split. Pick the period with `range` (7d, 30d, 90d or 365d up to today) or with `from` and `to`. Days follow `timezone`, UTC by default. `keywordIds` and `platforms` narrow the data, and `compare=true` adds the equally long period just before. Dates are publish dates.

## Query parameters

- `range` '7d' | '30d' | '90d' | '365d': A preset period up to today, 30d by default. Ignored when you send from or to.
- `from` string: Start date in `timezone`, as YYYY-MM-DD. That day is included.
- `to` string: End date in `timezone`, as YYYY-MM-DD, included. Defaults to today.
- `keywordIds` string[], nullable: Keeps these keyword ids only. Repeat the parameter or separate values with commas. Leave it out for all keywords.
- `platforms` string[]: Keeps these platforms only. Repeat the parameter or separate values with commas. Leave it out for all platforms.
- `compare` boolean: true adds the equally long period just before as `previous`.
- `timezone` string: The IANA time zone used to split days, such as America/New_York. Defaults to UTC. The zone's offset at the end of the period is used for the whole period.

## Response `200`

The keywords, the one with the most matches first

- ShareOfVoice
  - `window` object, required: Start and end of the period.
    - `from` string, required: The first day included.
    - `to` string, required: The last day included.
    - `days` integer, required: How many days the window spans.
    - `timezone` string, required: The IANA time zone used to split the days.
  - `data` object[], required: All keywords with matches in the window, the one with the most first.
    - `keyword` object, required: Which keyword the row covers.
      - `id` string, required: The keyword's id (kw_...).
      - `term` string, required: The term being tracked.
      - `kind` 'brand' | 'competitor' | 'topic', required: The keyword's kind, brand, competitor or topic.
      - `group` object, required: The keyword's group.
        - `id` string, required: The group's id (grp_...).
        - `name` string, required: Name of the group.
        - `externalId` string, nullable, required: An id from your own system, or null.
        - `isDefault` boolean, required: True for the workspace's default group. New keywords go there when you don't name a group.
    - `matched` integer, required: This keyword's match count in the window.
    - `relevant` integer, required: How many of them scored 40 or more.
    - `negative` integer, required: How many of them were negative.
    - `buyIntent` integer, required: How many of them were tagged buy_intent.
    - `share` number, nullable, required: The percentage of all brand and competitor matches, with one decimal. Null for topics, which are not part of the split.
    - `previous` object, nullable, required: With compare=true, this keyword for the prior period. Otherwise null.
      - `matched` integer, required: The keyword's matches during that period.

## Other responses

- `400`: The query is not valid
- `401`: The API key is missing or not valid

---

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