> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Discover entities in reporting
> Discover people, organizations and places appearing in reporting. For initial identity lookup, use `/api/v2/search?q=…`, select a candidate, then reuse its ID on the destination endpoint. This endpoint returns coverage metrics over the requested window. `search=` resolves a NAME across every entity universe we hold — news, the GDELT Cloud spine (SEC/EDGAR, GLEIF, GEM), sanctions lists, China-Abroad and Epoch — and each row reports the same `entity_id` join key as `/api/v2/search` (with legacy `id` retained), plus `match_type` / `match_reason` / `match_score` so the ranking can be audited rather than trusted. Metrics are the entity's resolved-layer coverage IN THE WINDOW, so a searched company with a successful empty coverage read reports zeros. Failed count reads report null with coverage_status; quiet reference matches remain available through search. Without search, the news-activity directory excludes measured-zero coverage rows. For the cross-source candidate list with per-source availability, use `/api/v2/search`. Native non-Latin-script matching is not yet complete, so use a common Romanized or English spelling for Cyrillic, Chinese and other non-Latin names for now. Native-script search support is on the way.
These return a 400 naming the reason and the alternative, so a filter that cannot work fails loudly instead of returning rows that ignore it.
- `entity` → 400 UNSUPPORTED_FILTER. This endpoint LISTS entities; it does not scope to one. `entity=` means "restrict to this entity's coverage" on /api/v2/events and /api/v2/stories, and it cannot mean that here. For the entities that appear alongside one entity use `co_occurring_with=`; for one entity's own record use `GET /api/v2/entities/{entity_id}`; for its coverage use `/api/v2/events?entity=` or `/api/v2/stories?entity=`. The handle is the same in all four. Use instead: `co_occurring_with=`, `GET /api/v2/entities/{entity_id}`, `GET /api/v2/events?entity=`, `GET /api/v2/stories?entity=`.
## OpenAPI
````yaml /api-reference/openapi-v2.json get /api/v2/entities
openapi: 3.0.3
info:
title: GDELT Cloud API v2
version: 2.0.0
description: >-
Clean v2 REST API for generated GDELT Cloud structured Events, clustered
Stories, linked Entities, summaries, admin1 discovery, significance ranking,
and paginated article evidence.
Event significance is a family-scoped weighted blend, renormalized so every
event family spans a true 0-1: each event's raw total is divided by the
maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90,
other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article
evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled
by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20,
systemic importance 0.15, propagation potential 0.10, market sensitivity
0.10. When magnitude is unmeasured its term AND its 0.20 weight are both
dropped. The four CAMEO+ metrics are rubric scores produced by published
formulas - ordinal ranking signals, not measurements, probabilities, or
predicted price moves. goldstein_scale is one canonical public metric,
populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful.
Story linked_event_count is a Story-to-Event link aggregate, not a distinct
Event total.
servers:
- url: https://gdeltcloud.com
description: Production
- url: http://localhost:3000
description: Local development
security:
- ApiKeyAuth: []
tags:
- name: Events
description: Coded CAMEO+ / conflict events — search, fetch, and summarize.
- name: Stories
description: Clustered narratives (stories) and their articles.
- name: Situations
description: >-
One real-world occurrence as the Stories and coded Events that belong to
it — stored, adjudicated membership (`meta.situation_source: curated`) or
a walked neighbourhood around a Story. Discovery, detail, four
independently paged member lists, and the only write on the core surface
(5 QU with an Idempotency-Key).
- name: Entities
description: >-
People & organizations — resolve a name to an entity, then fetch its
profile and tone. Also the publication activity journal
(/api/v2/activity): observed evidence of what was published about
identities and records — committed batches only, cursor-paged, never
source intake.
- name: Unified Search
description: >-
One fuzzy lookup across every id-space — start here with a name, take the
entity id, then reuse it on every other surface. This is the resolver the
rest of the API assumes you called first.
- name: Media Intelligence
description: >-
Press-coverage tone over time and share of voice against a peer set.
Requires the `can_use_tone` / `can_use_share_of_voice` entitlement; social
signal is an admin-only preview.
- name: Facilities
description: >-
Unified physical-asset directory — GEM energy assets, World Port Index
ports and Epoch AI data centers on one keyed surface, resolved to spine
owners. Requires the `can_use_facilities` entitlement.
- name: Monitors
description: >-
Organization-shared scheduled checks over the Core API, with email and
signed-webhook delivery. Monitor execution does not consume query units.
- name: Geography
description: >-
Country context and admin-1 geography: /api/v2/countries (publication
activity, reporting counts, dated economic and resource fundamentals,
facility and office inventories, directory mode over every registered
country) and admin-1 lookups.
- name: Government
description: >-
US federal awards (USAspending) and foreign-influence registrations (DOJ
NSD FARA), resolved onto the entity spine. Requires the `can_use_gov`
entitlement.
- name: Political Offices
description: >-
Public political offices and who holds them — legislatures, cabinets,
heads of state, courts and IGO posts, with the office start/end dates the
publisher states (valid time), resolved onto the entity spine. Actor
context for geopolitical analysis; NOT a PEP or sanctions-screening tool.
Requires the `can_use_offices` entitlement.
- name: Filings
description: >-
SEC EDGAR filings, XBRL financials, and relations extracted from filing
text. Requires the `can_use_filings` entitlement.
- name: Reference Data
description: >-
The GLEIF Global LEI Index — legal-entity reference data, consolidation
relationships, and LEI↔ISIN mappings. Requires the `can_use_gleif`
entitlement.
- name: Energy
description: Global Energy Monitor assets + ownership registry.
- name: AI Compute
description: >-
Epoch AI datasets — models, hardware, data centers, companies and chip
sales. Requires the `can_use_epoch_ai` entitlement.
- name: Macro Finance
description: >-
FRED economic time series — catalog, point-in-time observations and
releases. Requires the `can_use_macro` entitlement.
- name: Screening and Reference
description: >-
Restricted-party lists, name screening and ownership-chain exposure.
Requires the `can_use_screening` / `can_use_exposure` entitlement.
Analytical coverage, not an audit-grade compliance control.
- name: China
description: >-
China overseas development finance (AidData GCDF). Requires the
`can_use_china` entitlement.
- name: Maritime
description: >-
AIS-derived vessel flow — chokepoint transits, last-known vessel
positions, carriers, dwell and AIS-dark gaps. Terrestrial AIS only, so
coverage thins in open ocean. Requires the `can_use_maritime` entitlement.
- name: Atlas Intelligence
description: >-
Geopolitical-risk and posture indices computed from GDELT Cloud’s own
coded events, normalized to each place’s own frozen baseline.
- name: Briefs
description: Source-backed monitoring briefs.
- name: Meta
description: >-
Machine-readable discovery: the value vocabularies, the endpoint
contracts, and the query-unit cost model. Unmetered, so a client can check
before it spends.
paths:
/api/v2/entities:
get:
tags:
- Entities
summary: Discover entities in reporting
description: >-
Discover people, organizations and places appearing in reporting. For
initial identity lookup, use `/api/v2/search?q=…`, select a candidate,
then reuse its ID on the destination endpoint. This endpoint returns
coverage metrics over the requested window. `search=` resolves a NAME
across every entity universe we hold — news, the GDELT Cloud spine
(SEC/EDGAR, GLEIF, GEM), sanctions lists, China-Abroad and Epoch — and
each row reports the same `entity_id` join key as `/api/v2/search` (with
legacy `id` retained), plus `match_type` / `match_reason` /
`match_score` so the ranking can be audited rather than trusted. Metrics
are the entity's resolved-layer coverage IN THE WINDOW, so a searched
company with a successful empty coverage read reports zeros. Failed
count reads report null with coverage_status; quiet reference matches
remain available through search. Without search, the news-activity
directory excludes measured-zero coverage rows. For the cross-source
candidate list with per-source availability, use `/api/v2/search`.
Native non-Latin-script matching is not yet complete, so use a common
Romanized or English spelling for Cyrillic, Chinese and other non-Latin
names for now. Native-script search support is on the way.
These return a 400 naming the reason and the alternative, so a filter
that cannot work fails loudly instead of returning rows that ignore it.
- `entity` → 400 UNSUPPORTED_FILTER. This endpoint LISTS entities; it
does not scope to one. `entity=` means "restrict to this entity's
coverage" on /api/v2/events and /api/v2/stories, and it cannot mean that
here. For the entities that appear alongside one entity use
`co_occurring_with=`; for one entity's own record use `GET
/api/v2/entities/{entity_id}`; for its coverage use
`/api/v2/events?entity=` or `/api/v2/stories?entity=`. The handle is the
same in all four. Use instead: `co_occurring_with=`, `GET
/api/v2/entities/{entity_id}`, `GET /api/v2/events?entity=`,
`GET /api/v2/stories?entity=`.
operationId: search-entities-v2
parameters:
- name: date_start
in: query
required: false
schema:
type: string
format: date
description: >-
EVENT TIME — inclusive start of the window by when it HAPPENED
(YYYY-MM-DD). Windows are capped at 30 inclusive days. Use
consecutive date chunks; calendar months can exceed the cap. Follow
the endpoint's pagination guidance within each chunk. For when we
RECORDED it, use observed_start. Also accepts: `start_date`. Note:
validation is owned by the endpoint service because it depends on
composed or cross-parameter state; the published error semantics
above still apply.
example: '2026-08-01'
x-aliases:
- start_date
- name: date_end
in: query
required: false
schema:
type: string
format: date
description: >-
EVENT TIME — inclusive end of the window by when it HAPPENED
(YYYY-MM-DD). For when we RECORDED it, use observed_end. Also
accepts: `end_date`. Note: validation is owned by the endpoint
service because it depends on composed or cross-parameter state; the
published error semantics above still apply.
example: '2026-08-04'
x-aliases:
- end_date
- name: days
in: query
required: false
schema:
type: string
description: >-
Calendar-date window ending today, in days (max 30). `window=7d` and
`days=7` are equivalent. When omitted, entity coverage uses the last
30 calendar days with an observed-time bound over the same span.
There is no equivalent numeric default: sending days explicitly
selects calendar dates and removes the implicit observed-time bound.
Pass `days` explicitly, or `date_start`/`date_end`, whenever the
window matters. Also accepts: `window`. Note: validation is owned by
the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply.
example: '7'
x-aliases:
- window
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
description: >-
Rows per page. Default 25, max 100. Note: validation is owned by the
endpoint service because it depends on composed or cross-parameter
state; the published error semantics above still apply.
example: '25'
- name: cursor
in: query
required: false
schema:
type: string
description: >-
Opaque pagination cursor taken from the previous response's
`pagination.next_cursor`. Also accepts: `offset`. Note: validation
is owned by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply.
example: '25'
x-aliases:
- offset
- name: co_occurring_with
in: query
required: false
schema:
type: string
description: >-
Return the entities that appear ALONGSIDE this one — the entities
linked to the same Stories, over the same window, narrowed by every
other filter on this endpoint. Accepts a spine id (`e_…`), a news id
(`wiki:…`) or a name, resolved through the same arbiter as `entity=`
on `/api/v2/events` and `/api/v2/stories`, so one handle means the
same entity everywhere. The subject is never returned in its own
results. Co-occurrence is measured over SHARED STORIES — appearing
in the same coverage, which is not a claim that the two entities
interacted. A handle that resolves to nothing returns an EMPTY list
with a `linkage` reason in `applied_filters`, never the global top
entities. Note: validation is owned by the endpoint service because
it depends on composed or cross-parameter state; the published error
semantics above still apply. Full value list:
https://docs.gdeltcloud.com/reference/enums#entity_handle
example: e_0576e79c82962452
- name: country
in: query
required: false
schema:
type: string
description: >-
Country filter. Accepts ISO-3, ISO-2, FIPS or an English name;
comma-separate for OR. Matches the event's own location OR either
actor's origin country by default, so a result can include events
that happened elsewhere — set `country_match` to narrow it to
location only. The definition in force is echoed as
`applied_filters.country_match`. Also accepts: `country_iso3`.
Matched case-insensitively. Note: validation is owned by the
endpoint service because it depends on composed or cross-parameter
state; the published error semantics above still apply. Reference:
https://docs.gdeltcloud.com/reference/enums#country
example: UKR,RUS
x-aliases:
- country_iso3
- name: region
in: query
required: false
schema:
type: string
enum:
- Africa
- Asia
- Middle East
- Northern Africa
- Western Africa
- Eastern Africa
- Middle Africa
- Southern Africa
- Europe
- Eastern Europe
- South Asia
- Southeast Asia
- East Asia
- Central Asia
- North America
- Central America
- Caribbean
- South America
- Oceania
description: >-
One ACLED-style region. Expanded to its member countries. Note:
validation is owned by the endpoint service because it depends on
composed or cross-parameter state; the published error semantics
above still apply. Full value list:
https://docs.gdeltcloud.com/reference/enums#region
example: Middle East
- name: continent
in: query
required: false
schema:
type: string
enum:
- Africa
- Asia
- Europe
- North America
- South America
- Oceania
description: >-
One continent. Expanded to its member countries. Note: validation is
owned by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply. Full value list:
https://docs.gdeltcloud.com/reference/enums#continent
example: Europe
- name: category
in: query
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- Battles
- Protests
- Riots
- Explosions/Remote violence
- Violence against civilians
- Strategic developments
- POLITICAL
- CRIME
- ECONOMIC
- CORPORATE
- TECHNOLOGY
- INFRASTRUCTURE
- ENVIRONMENT
- HEALTH
- DEMOGRAPHIC
- INFORMATION
description: >-
Event category — an ACLED event type or a CAMEO+ domain.
Comma-separate for OR. Validated together with `subcategory`: an
impossible pair returns 400, never an empty 200. Also accepts:
`categories`. Matched case-insensitively. Note: validation is owned
by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply. Full value list:
https://docs.gdeltcloud.com/reference/enums#event_category
example: Protests
x-aliases:
- categories
- name: subcategory
in: query
required: false
schema:
type: string
description: >-
Sub-event type (Conflict) or CAMEO+ leaf code. Comma-separate
multiple values for OR. Scoped by `category` — sending it alone is
400 SUBCATEGORY_REQUIRES_CATEGORY and a pair that cannot exist is
400 INVALID_SUBCATEGORY_FOR_CATEGORY with the accepted values, so a
bad value is never an empty 200 (both verified 2026-08-13). The
taxonomy is closed and published in full, but PUBLICATION IS NOT
COVERAGE — a defined code can carry zero events in any given window,
and a few carry zero in most windows (`Sexual violence` is the
measured example: its definition boundary sends nearly all such
reporting to `Attack`). Before building a monitor on one code,
measure it: `GET /api/v2/events/summary?group_by=subcategory`
returns the codes that actually carry events in your window, with
counts. An empty 200 here means no coverage for that combination,
never zero real-world activity. Note: validation is owned by the
endpoint service because it depends on composed or cross-parameter
state; the published error semantics above still apply. Reference:
https://docs.gdeltcloud.com/reference/taxonomy-complete
example: Peaceful protest
- name: type
in: query
required: false
schema:
type: string
enum:
- PERSON
- ORGANIZATION
- PLACE
description: >-
Restrict to one entity type. `entity_type` is accepted as an alias
because that is the id `/meta/enums` publishes for this vocabulary.
Also accepts: `entity_type`. Note: validation is owned by the
endpoint service because it depends on composed or cross-parameter
state; the published error semantics above still apply. Full value
list: https://docs.gdeltcloud.com/reference/enums#entity_type
example: organization
x-aliases:
- entity_type
- name: search
in: query
required: false
schema:
type: string
description: >-
Entity NAME to resolve. Matched across every entity universe and
ranked by match quality (exact name, exact alias, acronym, prefix,
fuzzy) before coverage — see each row's `match_type` and
`match_reason`. Until native non-Latin-script matching ships, use a
common Romanized or English spelling for Cyrillic, Chinese, and
other non-Latin names. Also accepts: `q`. Note: validation is owned
by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply.
example: Infineon
x-aliases:
- q
- name: languages
in: query
required: false
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
ISO source-language filter. Restricts coverage metrics to articles
in those languages. Also accepts: `language`. Note: validation is
owned by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply. Observed vocabulary, measured 2026-08-10 (77 distinct
values). Values outside it are accepted, not rejected. Discover
current values: `GET /api/v2/stories?limit=1 (read
coverage.languages)`. Values seen in the corpus:
https://docs.gdeltcloud.com/reference/enums#coverage_language
example: ar,zh
x-aliases:
- language
- name: has_fatalities
in: query
required: false
schema:
type: boolean
description: >-
Restrict to entities linked to fatal events. Note: validation is
owned by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply.
example: 'true'
- name: civilian_targeting
in: query
required: false
schema:
type: boolean
description: >-
Restrict to entities linked to events coded as civilian targeting.
Note: validation is owned by the endpoint service because it depends
on composed or cross-parameter state; the published error semantics
above still apply.
example: 'true'
- name: sort
in: query
required: false
schema:
type: string
enum:
- significance
- recent
default: significance
description: >-
recent orders the bounded candidate page by candidate news-activity
date (latest_observed_news_date, day precision), breaking same-day
ties by candidate mention volume, then article volume, then stable
identity; registry or link processing times do not lead. With
significance, search resolves by match quality first. Explicit
recent preserves this order even with search or taxonomy filters;
resolved counts and latest_date do not reorder its fixed candidate
page. Quiet rows may shorten a page; follow next_cursor even after
an empty page. Note: validation is owned by the endpoint service
because it depends on composed or cross-parameter state; the
published error semantics above still apply. Full value list:
https://docs.gdeltcloud.com/reference/enums#sort
example: significance
- name: include_images
in: query
required: false
schema:
type: boolean
description: >-
Attach Wikipedia thumbnail/avatar URLs where available. Off unless
requested — the images cost an extra lookup. Note: validation is
owned by the endpoint service because it depends on composed or
cross-parameter state; the published error semantics above still
apply.
example: 'false'
- name: recorded_start
in: query
required: false
schema:
type: string
description: >-
Inclusive start of journal availability time, as an ISO UTC
timestamp. Supply both bounds. Includes late arrivals without
changing their original reporting dates. Cannot combine with
reporting-date filters. Note: validation is owned by the endpoint
service because it depends on composed or cross-parameter state; the
published error semantics above still apply.
example: '2026-09-06T00:00:00Z'
x-advanced: true
- name: recorded_end
in: query
required: false
schema:
type: string
description: >-
Exclusive end of journal availability time, as an ISO UTC timestamp.
Supply both bounds. Includes late arrivals without changing their
original reporting dates. Cannot combine with reporting-date
filters. Note: validation is owned by the endpoint service because
it depends on composed or cross-parameter state; the published error
semantics above still apply.
example: '2026-09-07T00:00:00Z'
x-advanced: true
- name: observed_start
in: query
required: false
schema:
type: string
description: >-
OBSERVED TIME — inclusive start of the window by when GDELT Cloud
RECORDED it, rather than when it happened: coding time on Events,
cluster-update time on Stories. The supported point-in-time lever on
this endpoint. For when it happened, use date_start. Accepts a
calendar date (`2026-08-01`, read as that day at 00:00:00Z) OR a
full instant (`2026-08-01T04:04:30Z`) — an instant is how you
express a sub-day window, which `date_start` cannot. Note:
validation is owned by the endpoint service because it depends on
composed or cross-parameter state; the published error semantics
above still apply.
example: '2026-08-01'
x-advanced: true
- name: observed_end
in: query
required: false
schema:
type: string
description: >-
OBSERVED TIME — exclusive upper bound on the recorded-at window
(coding time on Events, cluster-update time on Stories). To include
everything recorded through 2026-08-04, send 2026-08-05. Accepts a
calendar date or a full instant (`2026-08-05T04:04:30Z`); the
interval is half-open, so equal endpoints select no instant and are
refused. Note: validation is owned by the endpoint service because
it depends on composed or cross-parameter state; the published error
semantics above still apply.
example: '2026-08-04'
x-advanced: true
- name: country_match
in: query
required: false
schema:
type: string
enum:
- location_or_actor_origin
- location
default: location_or_actor_origin
description: >-
Which definition of "in this country" the `country` / `region` /
`continent` filters use. Defaults to the wider one, which is why
omitting it changes nothing. Applies to `region` and `continent`
too, since both expand into the same country set. Note that
`group_by=country` buckets on the event's own location, while the
default match also admits actor origin — so a filtered total and the
bucket for that same country can differ. Pass
`country_match=location` when you need the two to agree. Full value
list: https://docs.gdeltcloud.com/reference/enums#country_match
example: location
x-advanced: true
responses:
'200':
description: Entity cards
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginatedResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EntityCard'
examples:
entities:
value:
success: true
data:
- id: https://en.wikipedia.org/wiki/United_Nations
url: https://gdeltcloud.com/entities/e_united_nations
name: United Nations
type: organization
wikipedia_url: https://en.wikipedia.org/wiki/United_Nations
story_refs: []
event_refs: []
pagination:
limit: 25
cursor: null
next_cursor: eyJvZmZzZXQiOjI1fQ==
security:
- ApiKeyAuth: []
components:
schemas:
PaginatedResponse:
type: object
properties:
success:
type: boolean
enum:
- true
pagination:
$ref: '#/components/schemas/Pagination'
EntityCard:
type: object
description: >-
One canonical Entity with resolved news coverage in the requested
window. Explicit name search can retain reference entities without
measured news coverage. Entity Tone may be included on detail;
unavailable tone is not neutral.
properties:
id:
type: string
url:
type: string
format: uri
nullable: true
name:
type: string
description: >-
Canonical display name — the most-mentioned raw_name variant
pointing at this Wikipedia URL.
type:
type: string
nullable: true
enum:
- person
- organization
wikipedia_url:
type: string
format: uri
nullable: true
latest_date:
type: string
format: date
nullable: true
description: >-
Most recent date the Entity appeared in a Story or Event within the
requested window.
image_url:
type: string
format: uri
nullable: true
description: Best-effort Wikipedia thumbnail URL for UI rendering.
avatar_url:
type: string
format: uri
nullable: true
description: Best-effort compact avatar URL, usually the same as image_url.
wikipedia:
type: object
nullable: true
description: >-
Compact Wikipedia enrichment when available, including
thumbnail_url, description, page_url, and summary on detail
responses.
additionalProperties: true
metrics:
type: object
description: >-
Resolved coverage counts for the requested window and filters. NULL
means unavailable, never zero activity.
properties:
article_count:
type: integer
description: >-
Articles that mention this entity, across those Stories. This is
the entity's footprint, NOT the article volume of the Stories
themselves — that is larger, and /api/v2/stories carries it per
Story as metrics.article_count. NULL when the aggregate is
unavailable; zero only after a successful empty read.
nullable: true
story_count:
type: integer
description: >-
Distinct Stories in this window that mention this entity —
counted once each, never once per day they ran. The same
population /api/v2/stories?entity= pages through, and the same
number /api/v2/entities/{id} serves as metrics.story_count. NULL
when the aggregate is unavailable; zero only after a successful
empty read.
nullable: true
event_count:
type: integer
description: >-
Coded events linked to those Stories over the same window — the
events /api/v2/events?entity= returns. NULL when the aggregate
is unavailable; zero only after a successful empty read.
nullable: true
mention_count:
type: integer
nullable: true
description: >-
How many times this entity is mentioned across the articles of
those Stories. Higher than Articles when an article names the
entity more than once. NULL when the aggregate is unavailable;
zero only after a successful empty read.
story_refs:
type: array
items:
type: object
event_refs:
type: array
items:
type: object
entity_tone:
type: object
nullable: true
description: >-
Present on Entity detail when include_tone=true and the caller is
allowed to access preview tone metadata. tone_status may be scored,
reviewable, partial, or not_available.
properties:
tone_status:
type: string
enum:
- scored
- reviewable
- partial
- not_available
coverage:
type: object
additionalProperties: true
latest_series:
type: array
items:
type: object
by_language:
type: array
description: >-
Per-language tone over ALL scored Stories in the window (never
the bounded evidence sample) — the same rows the tone endpoints
return as `language_breakdown`, which is where the field comes
from. Use it to compare how an entity is covered across
languages, e.g. markedly more negative in one language than
another. Aggregated over the entity this detail response is
about. A component (`avg_news_tone_score` /
`avg_social_tone_score`) is `null` when no evidence of that kind
was scored in that language — never 0, which is the middle of
the neutral band and would report a reading nobody took; its
paired article count is 0 in exactly those rows.
items:
type: object
properties:
language:
type: string
avg_tone_score:
type: number
nullable: true
description: >-
Blended tone for Stories covered in this language,
weighted by that language’s evidence-item count.
avg_news_tone_score:
type: number
nullable: true
description: News-only tone in this language. null = not measured.
avg_social_tone_score:
type: number
nullable: true
description: Social-only tone in this language. null = not measured.
news_article_count:
type: integer
social_article_count:
type: integer
article_count:
type: integer
description: >-
Total evidence items in this language across the scored
Stories — the denominator behind avg_tone_score.
scored_rows:
type: integer
description: Scored entity-Story-day rows covered in this language.
analytics_url:
type: string
nullable: true
methodology:
type: object
additionalProperties: true
cooccurrences:
type: array
description: >-
Co-occurring entities — people/organizations that appear in the same
Stories as this entity within the window, ranked by shared-Story
count. Returned on Entity detail. Each item: name, type
(person|organization), wikipedia_url, story_count (shared Stories),
source ('news'), url (entity page).
items:
type: object
properties:
name:
type: string
type:
type: string
nullable: true
enum:
- person
- organization
wikipedia_url:
type: string
nullable: true
story_count:
type: integer
source:
type: string
url:
type: string
nullable: true
timeline:
type: array
description: >-
Per-day activity for the entity over the window (Entity detail).
Each item: date, article_count, mention_count.
items:
type: object
source_mix:
type: array
description: >-
Top news domains covering the entity over the window (Entity
detail). Each item: domain, article_count, story_count.
**Deprecated 2026-08-29; scheduled for removal on or after
2026-09-28.** It is a warehouse-only aggregation on a
customer-facing read path. The same query shape on the public entity
page measured ~9.8% of ALL production ClickHouse memory on
2026-08-02 — one query, one panel, sixteen rows — and no settled
column can answer it, so it cannot be moved onto the serving layer
the rest of the endpoint reads from. There is no replacement, and
that is the point: the field cannot be served correctly. The settled
serving layer carries only a capped `top_article_domains` list and a
`distinct_domain_count`; per-article domain exists in the warehouse
alone. For per-outlet coverage of a Story, read `source_count` and
the domain list on `GET /api/v2/stories/{id}`.
items:
type: object
deprecated: true
map_pins:
type: array
description: >-
Geo-located Events linked to the entity (Entity detail), for map
rendering. Each item: event_uid, event_family, event_date, title,
country, category, latitude, longitude.
items:
type: object
sources:
type: object
nullable: true
description: >-
Per-source entitlement control-plane on Entity detail: for each data
source (news, events, tone, gem, sec, sanctions, china, epoch_ai,
facilities, gov, share_of_voice) whether the caller's plan is
entitled, plus availability for entitled sources. Non-entitled
sources report a uniform locked state and omit availability (no
availability leak). The corresponding section objects (news, events,
tone, sec, ...) appear at the top level only for entitled sources.
additionalProperties: true
latest_observed_news_date:
type: string
format: date
nullable: true
description: >-
Entity-list recent ordering key: latest dated Story/Event mention in
the candidate news index, at day precision. Separate from resolved
coverage latest_date/counts; never a registry-update or
link-processing timestamp. Null for reference-only name matches.
coverage_status:
type: string
enum:
- available
- no_coverage
- partial
- unavailable
description: >-
Entity-list windowed metrics: available = measured activity;
no_coverage = successful reads measured zero; partial = some
aggregates unavailable; unavailable = no aggregate established. An
unavailable count is null. Name search may retain quiet reference
matches.
recorded_at:
type: string
description: >-
Committed availability timestamp, present for recorded-interval
queries.
published_at:
type: string
description: >-
Original publication timestamp, present for recorded-interval
queries.
public_official:
type: object
properties:
checked:
type: boolean
description: >-
False when office evidence or canonical identity could not be
checked.
is_public_official:
type: boolean
nullable: true
description: >-
Published office evidence exists. Null means unavailable, not a
negative finding.
status:
type: string
enum:
- current
- former
- unknown
nullable: true
description: >-
Publisher status across recorded terms. Former requires all
terms to be explicitly ended; missing dates never infer status.
total:
type: number
nullable: true
description: Distinct recorded offices, independent of the bounded preview.
offices:
type: array
items:
type: object
properties:
office_id:
type: string
name:
type: string
country_iso3:
type: string
nullable: true
description: Office jurisdiction, not citizenship.
status:
type: string
enum:
- current
- ended
- unknown
start_date:
type: string
nullable: true
end_date:
type: string
nullable: true
evidence_date:
type: string
nullable: true
sources:
type: array
items:
type: object
properties:
source_key:
type: string
url:
type: string
nullable: true
required:
- source_key
- url
required:
- office_id
- name
- country_iso3
- status
- start_date
- end_date
- evidence_date
- sources
truncated:
type: boolean
required:
- checked
- is_public_official
- status
- total
- offices
- truncated
Pagination:
type: object
properties:
limit:
type: integer
cursor:
type: string
nullable: true
next_cursor:
type: string
nullable: true
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: gdelt_sk_...
description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'
````