---
title: "Get share of voice"
method: GET
path: "/api/mcp/projects/{projectId}/share-of-voice"
tags: ["Share of Voice"]
---

# Get share of voice

`GET /api/mcp/projects/{projectId}/share-of-voice`

## Request

- Base URL: `https://app.searchable.com`
- URL: `https://app.searchable.com/api/mcp/projects/{projectId}/share-of-voice`
- Auth: HTTP bearer

Brand vs competitor share of voice — mention-share percentage, rank among all tracked entities, and each entity's point change against the equal-length window just before the requested one (null when either window has no mentions). mentions/citations are always null here (not computed by the backing service, and not shown by the in-app view either) — use /competitors for those. Pass unbranded=true or branded=true to restrict by prompt brand state. `days` defaults to 30, max 365.

## Path parameters

- `projectId` string, uuid, required

## Query parameters

- `days` integer
- `platform` string
- `topicId` string, uuid
- `unbranded` 'true'
- `branded` 'true'
- `competitorType` 'all' | 'direct' | 'serp'
- `country` string
- `locationId` string
- `compare` 'previous_period' | 'previous_year'
- `from` string
- `to` string

## Response `200`

Share of voice.

- ShareOfVoiceResponse
  - `project` ProjectRefWithBrand, required
    - `id` string, uuid, required
    - `name` string, required
    - `domain` string, nullable, required
    - `brandName` string
  - `brand` object, required
    - `name` string
    - `sov` number
    - `rank` integer, nullable
    - `delta` number, nullable: Point change against the equal-length window just before the requested one; null when either window has no mentions.
  - `competitors` object[], required
    - `name` string
    - `domain` string, nullable
    - `competitorType` 'direct' | 'serp': `direct` (a competitor you track on purpose) or `serp` (one found in AI answers), as the app's Competitors list labels it. Filter with the `competitorType` query parameter.
    - `sov` number
    - `rank` integer
    - `delta` number, nullable: Point change against the equal-length window just before the requested one; null when either window has no mentions.
    - `mentions` unknown
    - `citations` unknown
    - `previousSov` number: Present only when `compare` was passed: the entity's share in the previous window (0 when absent from it)
    - `sovDelta` number: Present only when `compare` was passed: sov minus previousSov
  - `totalCompetitors` integer
  - `dateRange` DateRange, required: The resolved lookback window for this response.
    - `from` string, date-time, required
    - `to` string, date-time, required
  - `comparison` object: Present only when `compare` was passed. Per-competitor previous shares ride INLINE on each competitor row (`previousSov`/`sovDelta`, matched by entity display name — the share-of-voice entity identity).
    - `mode` 'previous_period' | 'previous_year'
    - `dateRange` DateRange: The resolved lookback window for this response.
      - `from` string, date-time, required
      - `to` string, date-time, required
    - `brand` object
      - `previousSov` number
      - `sovDelta` number
      - `previousRank` integer, nullable

## Other responses

- `400`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `401`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `403`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `404`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.
- `429`: Rate limited. Usually the per-API-key REST limit (600 requests/minute); on Google-backed endpoints it can also relay an upstream Google rate limit. `Retry-After` (seconds) is present when the limit was applied by Searchable's own rate limiter; it may be absent when an upstream provider rate-limits.
- `504`: Error response. `code` is the machine-readable reason — see the [error reference](/api/errors) for the full catalog and remediation per code.

## Changes

- **2026-11-03** `28a5e2a65cd3`: 2 breaking, 54 warning, 8 info
  - the response property `brand/delta` became nullable for the status `200`
  - the response property `competitors/items/delta` became nullable for the status `200`
  - added the new `duplicate_scope` enum value to the `code` response property for the response status `400`
  - added the new `duplicate_scope` enum value to the `code` response property for the response status `401`
  - …60 more

[Operation history](https://skmtc.dev/searchable/apis/searchable-rest-api/changes/api/mcp/projects/:projectId/share-of-voice/get.md)

---

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