---
title: "Entity tone"
method: GET
path: "/api/v2/entity-tone"
tags: ["Media Intelligence"]
---

# Entity tone

`GET /api/v2/entity-tone`

Entity-conditioned media tone, risk, and confidence over a window, with cited evidence. Resolve the entity first with /api/v2/search. Requires a plan with Entity media tone access (`can_use_tone`) — the Analyst, Media Intelligence, Geopolitical Intelligence, and Global Intelligence plans.

## Query parameters

- `entity_id` string
- `entity_search` string
- `q` string
- `date_start` string
- `date_end` string
- `days` integer
- `languages` string
- `include_evidence` boolean
- `evidence_limit` integer
- `limit` integer

## Response `200`

Entity tone.

- 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
  - `entity_coverage` object[]
    - `canonical_entity_id` string
    - `display_name` string
    - `entity_type` string
    - `wikipedia_url` string
    - `tone_status` string
    - `row_count` integer
    - `candidate_story_count` integer
    - `candidate_article_count` integer
    - `candidate_mention_count` integer
    - `scored_story_count` integer
  - `rows` object[]
    - `canonical_entity_id` string
    - `display_name` string
    - `entity_type` string
    - `bucket_date` string
    - `bucket_granularity` string
    - `denominator_hash` string
    - `candidate_story_count` integer
    - `scored_story_count` integer
    - `scored_article_count` integer
    - `insufficient_evidence_count` integer
    - `needs_review_count` integer
    - `avg_tone_score` number
    - `avg_risk_score` number
    - `avg_confidence` number
    - `coverage_ratio` number
    - `agreement_score` number
    - `languages` string[]
    - `top_positive_story_ids` string[]
    - `top_negative_story_ids` string[]
    - `top_risky_story_ids` string[]
  - `methodology` object
    - `unit` string
    - `tone_score` string
    - `risk_score` string
    - `missing_tone` string

## Other responses

- `401` — Missing/invalid API key
- `403` — Plan required (PLAN_REQUIRED) — the caller's plan does not carry the required source entitlement.
- `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/versions/01aaa6255180/schema)