Discover entities in reporting

GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....

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.

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.

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.

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.

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.

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

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

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

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

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

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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