---
title: "Share of Voice"
method: GET
path: "/api/v2/share-of-voice"
tags: ["Media Intelligence"]
---

# Share of Voice

`GET /api/v2/share-of-voice`

An entity's share of press attention against a peer denominator over a window, with a plot-ready timeline. Plan-gated (can_use_share_of_voice; admins always).

## Query parameters

- `entity_id` string
- `entity_search` string
- `category` string
- `topic` string
- `query` string
- `languages` string
- `date_start` string
- `date_end` string
- `days` integer
- `limit` integer

## Response `200`

Share of Voice.

- object
  - `status` string
  - `start_date` string
  - `end_date` string
  - `entities` string[]
  - `resolved_entities` object[]
    - `input` string
    - `canonical_entity_id` string
    - `display_name` string
    - `entity_type` string
    - `wikipedia_url` string
    - `match_type` string
  - `unresolved_terms` unknown[]
    - unknown
  - `coverage` object
    - `observed_entities` string[]
    - `not_observed_entities` unknown[]
      - unknown
    - `note` string
  - `denominator` object
    - `hash` string
    - `scope` object
      - `category` string
      - `languages` unknown[]
        - unknown
      - `source_set` unknown[]
        - unknown
      - `countries` unknown[]
        - unknown
      - `regions` unknown[]
        - unknown
      - `topic` string
    - `unit` string
    - `validation` string
    - `source` string
    - `total_story_count` integer
    - `total_article_count` integer
    - `total_weight` integer
    - `search_mode` string
    - `semantic_min_score` unknown
    - `semantic_candidate_limit` unknown
    - `semantic_truncated` boolean
  - `rows` object[]
    - `run_id` string
    - `bucket_date` string
    - `canonical_entity_id` string
    - `display_name` string
    - `entity_type` string
    - `wikipedia_url` string
    - `entity_status` string
    - `denominator_hash` string
    - `denominator_profile_json` string
    - `denominator_story_count` integer
    - `denominator_article_count` integer
    - `denominator_weight` integer
    - `entity_story_count` integer
    - `entity_article_count` integer
    - `entity_weight` integer
    - `story_share` number
    - `article_share` number
    - `weighted_share` number
    - `avg_tone_score` number
    - `avg_risk_score` number
    - `tone_coverage_ratio` number
    - `coverage_warnings` unknown[]
      - unknown
  - `methodology` object
    - `default_metric` string
    - `denominator_required` boolean
    - `note` string

## Other responses

- `401` — Missing/invalid API key
- `403` — Plan required (PLAN_REQUIRED) — the caller's plan does not carry `can_use_share_of_voice`.
- `500` — Server error

---

[API](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2.md) · [All operations](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gdeltcloud/gdelt-cloud-api-v2/revisions/01aaa6255180/schema)