Search Stories
Search clustered Stories for narrative and article evidence with broad result coverage by default. Story cards include linked Events, linked Entities, normalized geo, metrics, public URLs, and top 3 inline articles. Use category/subcategory to filter by linked Event taxonomy.
Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Query Parameters
Inclusive start date in YYYY-MM-DD, matched against the event or story date. Alias start_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
"2026-04-11"
Inclusive end date in YYYY-MM-DD, matched against the event or story date. Alias end_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
"2026-04-17"
Country filter, resolved through the shared resolveCountryInput layer so a plain English country name (United States), an ISO-2 code (US), an ISO-3 code (USA), or a common alias (UK, UAE, Czechia) all work interchangeably; output normalizes to the country name. Accepts a comma-separated list (any part unresolvable → 400 INVALID_COUNTRY), and can be combined with region/continent.
"Lebanon"
Plain English region such as Middle East, Western Africa, South Asia, or Europe. The backend expands this value to an ISO-3 country list; Events match location and actor-origin countries, while Stories match linked Event primary location.
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 "Middle East"
Plain English continent such as Africa, Asia, Europe, North America, South America, or Oceania. The backend expands this value to an ISO-3 country list; Events match location and actor-origin countries, while Stories match linked Event primary location.
Africa, Asia, Europe, North America, South America, Oceania "Africa"
Optional state/province/admin1 location filter. Discover valid values through /api/v2/geo/admin1. Filters Event or Story location only, not actor origin.
"Beirut"
Bounding box lat_min,lon_min,lat_max,lon_max. Keeps stories with AT LEAST ONE linked event inside the box — the same linked-event geography semantics as country/admin1. Note the returned linked_event_count / fatalities stay FULL-story aggregates, not box-restricted. Malformed or out-of-range values return 400 INVALID_BBOX.
Stable linked Event product category. Use a Conflict event type such as Battles, Protests, or Explosions/Remote violence, or one CAMEO+ domain such as POLITICAL, INFRASTRUCTURE, or CRIME; values may be single or comma-separated. On Story endpoints this filters linked Event evidence. Use story_category only for legacy Story-cluster categories such as conflict_security. Full list: Taxonomy & Codes.
"Battles"
Legacy Story-cluster category filter such as conflict_security or cameoplus_infrastructure. Prefer linked Event category/subcategory for product taxonomy filtering.
conflict_security, cameoplus_political, cameoplus_crime, cameoplus_economic, cameoplus_corporate, cameoplus_technology, cameoplus_infrastructure, cameoplus_environment, cameoplus_health, cameoplus_demographic, cameoplus_information "conflict_security"
Deprecated alias for category on Story endpoints. Prefer category=Battles or a CAMEO+ domain such as category=CRIME. Full list: Taxonomy & Codes.
More specific linked Event subtype, CAMEO+ event description, or CAMEO+ code. Requires parent category and must belong to at least one selected category. For Conflict categories, use sub-event types such as Armed clash, Peaceful protest, or Air/drone strike. Validation errors include accepted_values, nearest_values when practical, and a corrected example. Full list: Taxonomy & Codes.
"Armed clash"
Deprecated legacy CAMEO+ domain enum. Prefer category/categories for new integrations; retained for backwards compatibility. Full list: Taxonomy & Codes.
POLITICAL, ECONOMIC, CORPORATE, TECHNOLOGY, INFRASTRUCTURE, HEALTH, DEMOGRAPHIC, INFORMATION, ENVIRONMENT, CRIME Free-text semantic search. The API ranks the filtered candidate set by semantic similarity against stored Event or Story representations. It is not a lexical keyword filter and has no public similarity cutoff.
"attacks on energy infrastructure"
For Stories, set true to require linked structured Events or false for Stories without linked Events.
true
Set true for fatality monitoring. v2 intentionally exposes only this boolean fatality filter.
true
Filter Conflict-linked evidence by ACLED civilian_targeting. true keeps records where civilians are the primary target; false excludes those records.
Minimum Story article count.
x >= 02
Maximum Story article count.
x >= 025
Filter to items with at least one linked article in these source (origin) languages. Comma-separated ISO codes — en, zh, ar, es, fr, … — normalized case-insensitively and OR'd together; the alias language is accepted. Unknown codes are dropped rather than erroring.
"en,zh"
Include best-effort representative article image URLs on each row — a top-level image_url plus top_articles[].image_url. Defaults to true; set false to skip image enrichment for a lighter, faster response.
true
significance is the default analyst ranking. Use recent when freshness matters more than importance.
significance, recent "significance"
Number of records to return.
1 <= x <= 10025
Pagination cursor from pagination.next_cursor.