Search Events

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, a request without entity filters uses the last 24 hours; entity filters use 30 days. Read meta.query_window for the actual bounds. 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.

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

State or province (admin1), not a city. Discover valid values with GET /api/v2/geo/admin1?country=. 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#admin1

Point proximity lat,lon, combined with radius_km. The box is used for index pruning and rows are refined by true great-circle distance. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Radius in km for point proximity. Default 100, capped 2000. 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 an entity's resolved coverage. Accepts a spine id (e_…), a news id (wiki:…) or a name, resolved through the shared arbiter so the same handle means the same entity on every endpoint. Accepts up to 25 comma-separated handles, which are UNIONED: a row is returned if ANY handle matches, never only the rows matching all of them. Every handle resolves through that same arbiter, so a handle means the same entity alone or in a list. A handle that resolves to nothing contributes nothing — it never widens the result — and is named in applied_filters.entity_handles_unresolved. More than 25 handles is refused with 400 MULTIPLE_ENTITY_HANDLES rather than truncated. Also accepts: entity_id, 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

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

Significance lower bound (0–1). 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/metrics#significance

Significance upper bound (0–1). 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/metrics#significance

Search interpretation. semantic (default) retrieves a bounded conceptual relevance pool. lexical filters the complete serving set for a case-insensitive literal phrase in Events title/summary or Stories title before pagination; no stemming or boolean parsing. Lexical mode requires a supported serving snapshot and never falls back to the warehouse. Full value list: https://docs.gdeltcloud.com/reference/enums#reporting_search_mode

Search text. With search_mode=lexical this is a literal phrase in served Events title/summary or Stories title. By default the string is embedded and ranked by cosine similarity, so results are conceptual neighbours rather than substring matches. There is no boolean parser: a query shaped a OR b is reduced to its first term and the response says so. Costs an embedding call and can return 503 SEMANTIC_SEARCH_UNAVAILABLE. 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.

Ranking. A bare search with no explicit sort ranks by relevance instead. Full value list: https://docs.gdeltcloud.com/reference/enums#sort

Restrict to events with a non-zero fatality count. CONFLICT FAMILY ONLY. fatalities is an ACLED-family observable; the CAMEO+ family has no fatality field, so its events carry fatalities: null (never a fabricated 0) and can never satisfy true. Over 2026-08-06..13 that was 92.5% of all events, including every ENVIRONMENT, INFRASTRUCTURE and HEALTH event — so a disaster or industrial death toll is NOT in this filter, and the total it sums is the armed-conflict toll, not a global one. false is not the complement: it returns both a conflict event coded with a real 0 and every event that has no fatality observable at all, so it means "not known to be lethal", never "known to be non-lethal". For a lethality screen across all families use significance_min (cross-domain by construction) or goldstein_scale_max — Goldstein is signed, so an upper bound like goldstein_scale_max=-5 selects the strongly conflictual end — and read fatalities off the card to tell a measured 0 from an absent observable. 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 events coded as targeting civilians. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Source-language filter (ISO 639-1/2) on the linked Story's coverage. 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. Reference: https://docs.gdeltcloud.com/reference/enums#coverage_language

Attach article images to each card. Off by default. When enabled, entity thumbnails are also included unless include_entity_images=false. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Include entity thumbnails when include_images=true. Defaults to true, but has no effect while include_images is false or omitted. Pass false to skip the additional Wikipedia lookups while retaining article images. 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. Event and Story lists return only identities first published in this interval. Baseline identities, updates, removals, and returning identities are excluded. Use /api/v2/activity for changes. 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. Event and Story lists return only identities first published in this interval. Baseline identities, updates, removals, and returning identities are excluded. Use /api/v2/activity for changes. 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

Bounding box lat_min,lon_min,lat_max,lon_max. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.

Origin country of the ACTING side. Combine with target_actor_country to express a direction — source_actor_country=CHN&target_actor_country=USA,GBR is "China acting on those countries", which country= cannot say. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike country, region and continent do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. 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#country

Origin country of the RECEIVING side — the actor the action was directed at. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike country, region and continent do not expand onto the actor side. On CAMEO+ events the source actor IS the performer of the action; on conflict (ACLED) events the first actor is the PRIMARY actor and not necessarily the initiator, so this asserts involvement in that role rather than who started it. 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#country

Origin country of EITHER side, without regard to direction. This is the actor-origin half of what country= matches, on its own — use it to exclude events that merely happened in a country without any actor from it. Accepts ISO-3, ISO-2, FIPS or an English country name; comma-separate for OR. Unlike country, region and continent do not expand onto the actor side. 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#country

Coverage matching: Stories mentioning or linking the entity and the Events those Stories carry. The default and only supported policy; it does not establish actor participation or material involvement. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_match

Which canonical ids the handle stands for. expand (default) also matches the sibling ids the entity arbiter has already merged into the same real-world entity — a Wikipedia identity minted twice under different URL spellings, for instance — and echoes the union back as applied_filters.entity_ids_expanded. exact restricts to the one canonical id the handle resolves to, reproducing the pre-2026-08-25 counts. Full value list: https://docs.gdeltcloud.com/reference/enums#entity_family

Restrict to the OFFICE-HOLDERS of a political office: the Wikidata QID of the office (Q…) or the p_… id /api/v2/offices serves. Resolves to every holder whose published term overlaps the window (or office_as_of, when sent), then scopes exactly as entity=<those holders> would — a row is returned if ANY holder matches, and it is UNIONED with entity= when both are sent. A name is refused with 400; resolve it with GET /api/v2/offices?q= first. A roster of more than 1,000 holders inside the window is refused with 400 OFFICE_SCOPE_TOO_LARGE, never truncated. Holders reach the news layer only through a Wikipedia identity, so applied_filters.office_holders discloses how many of the roster are bridged_to_news versus unbridged — an unbridged holder carries no key coverage matching can match on and contributes no rows, so the counts are a FLOOR on the office's real coverage rather than a measurement of it. Each matched row carries entity_link.via: "office" with entity_link.entity naming the HOLDER (a spine id), not the office. Full value list: https://docs.gdeltcloud.com/reference/enums#office_id

VALID TIME for office= — scope to whoever held the office ON this date (YYYY-MM-DD) rather than to everyone whose term overlaps the window. This is the publisher's start/end clock, not what we knew then: it is NOT the knowledge-time as_of and is not gated by it. Office-holders with no published start date cannot be placed on a date and are excluded (counted in applied_filters.office_holders.undated_excluded), never fabricated. Ignored without office.

Confidence lower bound (0–1). 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/metrics#confidence

Confidence upper bound (0–1). 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/metrics#confidence

Goldstein scale lower bound (-10–10). 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/metrics#goldstein_scale

Goldstein scale upper bound (-10–10). 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/metrics#goldstein_scale

Magnitude lower bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/magnitude

Magnitude upper bound (0–10). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/magnitude

Systemic importance lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/systemic-importance

Systemic importance upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/systemic-importance

Propagation potential lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/propagation-potential

Propagation potential upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/propagation-potential

Market sensitivity lower bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/market-sensitivity

Market sensitivity upper bound (0–1). Published only for the cameoplus family — filtering on it excludes every event outside that family. Published only for the cameoplus family; filtering on it excludes every other family. 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/metrics/market-sensitivity

Geo precision lower bound (1–3). 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/metrics#geo_precision

Geo precision upper bound (1–3). 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/metrics#geo_precision

Add pagination.estimated_total — how many events match the filters, ignoring the page. Off by default because it costs a second scan of the same window. Counted from the SAME filters and the same row source as the page, so it always describes the result set you are walking. It is null (not a number) on a search= request: semantic retrieval is bounded by a candidate cap, so any total there would describe the candidate pool rather than the matching events. Without it, pagination.next_cursor still tells you whether more rows exist — non-null means yes, null means the walk is finished.