> ## 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. # Search Events > Search generated structured Events with broad result coverage by default. Use this for incident-level Conflict and CAMEO+ records with normalized geo, actors, categories, subcategories, metrics, linked Stories, linked Entities, and top article evidence. ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/events 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: Entities description: >- People & organizations — resolve a name to an entity, then fetch its profile and tone. - name: Geography description: Admin-1 geography lookups. - name: Energy description: Global Energy Monitor assets + ownership registry. - name: Facilities description: >- Unified physical-asset directory — GEM energy assets + World Port Index ports + Epoch AI data centers on one keyed surface, resolved to spine owners. Plan-gated (Analyst plan and up). - name: Screening and Reference description: >- Restricted-party lists, screening, and ownership-chain exposure. Plan-gated (`can_use_screening` / `can_use_exposure`). - name: China description: >- China overseas development finance (AidData GCDF). Plan-gated (`can_use_china`). - name: Media Intelligence description: >- Entity tone (`can_use_tone`) and Share of Voice (`can_use_share_of_voice`) are plan-gated. Social signal remains an admin-only preview. - name: Filings description: >- SEC EDGAR filings, XBRL financials, and AI-extracted relations. Requires a plan with SEC filings access (`can_use_filings`) — the Corporate & Supply Chain plan and above. - name: Macro Finance description: >- FRED economic time series (catalog, point-in-time observations, releases). Plan-gated (`can_use_macro`). - name: Maritime description: >- AIS-derived vessel-flow signals across maritime chokepoints — chokepoint transits, last-known vessel positions, carriers, dwell, and AIS-dark gaps. Plan-gated (`can_use_maritime`). - name: Briefs description: Source-backed monitoring briefs. paths: /api/v2/events: get: tags: - Events summary: Search Events description: >- Search generated structured Events with broad result coverage by default. Use this for incident-level Conflict and CAMEO+ records with normalized geo, actors, categories, subcategories, metrics, linked Stories, linked Entities, and top article evidence. operationId: search-events-v2 parameters: - $ref: '#/components/parameters/dateStart' - $ref: '#/components/parameters/dateEnd' - $ref: '#/components/parameters/country' - $ref: '#/components/parameters/region' - $ref: '#/components/parameters/continent' - $ref: '#/components/parameters/admin1' - $ref: '#/components/parameters/eventsBbox' - $ref: '#/components/parameters/eventsNear' - $ref: '#/components/parameters/eventsLat' - $ref: '#/components/parameters/eventsLon' - $ref: '#/components/parameters/eventsRadiusKm' - $ref: '#/components/parameters/eventFamily' - $ref: '#/components/parameters/category' - $ref: '#/components/parameters/subcategory' - $ref: '#/components/parameters/domain' - $ref: '#/components/parameters/search' - $ref: '#/components/parameters/hasFatalities' - $ref: '#/components/parameters/civilianTargeting' - $ref: '#/components/parameters/significanceMin' - $ref: '#/components/parameters/significanceMax' - $ref: '#/components/parameters/confidenceMin' - $ref: '#/components/parameters/confidenceMax' - $ref: '#/components/parameters/goldsteinScaleMin' - $ref: '#/components/parameters/goldsteinScaleMax' - $ref: '#/components/parameters/goldsteinSeverityMin' - $ref: '#/components/parameters/goldsteinSeverityMax' - $ref: '#/components/parameters/magnitudeMin' - $ref: '#/components/parameters/magnitudeMax' - $ref: '#/components/parameters/systemicImportanceMin' - $ref: '#/components/parameters/systemicImportanceMax' - $ref: '#/components/parameters/propagationPotentialMin' - $ref: '#/components/parameters/propagationPotentialMax' - $ref: '#/components/parameters/marketSensitivityMin' - $ref: '#/components/parameters/marketSensitivityMax' - $ref: '#/components/parameters/languages' - $ref: '#/components/parameters/includeImages' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/cursor' responses: '200': description: Event cards content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: data: type: array items: $ref: '#/components/schemas/EventCard' sort: $ref: '#/components/schemas/Sort' examples: events: value: success: true data: - id: conflict_13e29fd7 url: https://gdeltcloud.com/story/example-story primary_story_url: https://gdeltcloud.com/story/example-story family: conflict title: Attack in Delft summary: A conflict Event coded from linked source articles. event_date: '2026-04-15' category: Violence against civilians subcategory: Attack domain: CONFLICT event_code: conflict_13e29fd7 geo: country: South Africa region: Southern Africa continent: Africa admin1: Western Cape location: Delft latitude: -33.955 longitude: 18.634 actors: - name: Unknown armed actor country: null role: actor1 metrics: significance: 0.3585 goldstein_scale: -7 magnitude: null systemic_importance: null propagation_potential: null market_sensitivity: null confidence: 0.82 article_count: 1 has_fatalities: true fatalities: 4 story_refs: - id: story_123 url: https://gdeltcloud.com/story/example-story title: Delft mass shooting coverage story_date: '2026-04-15' article_count: 1 entity_refs: [] top_articles: - url: https://www.example.com/delft-mass-shooting title: 'Delft mass shooting: child among 4 killed' domain: example.com rank: 1 pagination: limit: 25 cursor: null next_cursor: eyJvZmZzZXQiOjI1fQ== sort: significance '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl "https://gdeltcloud.com/api/v2/events" \ -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" components: parameters: dateStart: name: date_start in: query description: >- 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. schema: type: string format: date example: '2026-04-11' example: '2026-04-11' dateEnd: name: date_end in: query description: >- 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. schema: type: string format: date example: '2026-04-17' example: '2026-04-17' country: name: country in: query description: >- 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`. schema: type: string example: Lebanon example: Lebanon region: name: region in: query description: >- 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. schema: type: string example: Middle East 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 example: Middle East continent: name: continent in: query description: >- 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. schema: type: string example: Africa enum: - Africa - Asia - Europe - North America - South America - Oceania example: Africa admin1: name: admin1 in: query description: >- Optional state/province/admin1 location filter. Discover valid values through `/api/v2/geo/admin1`. Filters Event or Story location only, not actor origin. schema: type: string example: Beirut example: Beirut eventsBbox: name: bbox in: query required: false schema: type: string pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?,-?\d+(\.\d+)?$ example: 11.5,42.5,13.5,44.5 description: >- Geographic bounding box on event latitude/longitude, formatted as lat_min,lon_min,lat_max,lon_max. Use for sub-country precision (e.g. a strait or port area). Combine with country or use alone; lat must be in [-90,90] and lon in [-180,180]. example: 11.5,42.5,13.5,44.5 eventsNear: name: near in: query required: false schema: type: string pattern: ^-?\d+(\.\d+)?,-?\d+(\.\d+)?$ example: 30.7,32.3 description: >- Proximity filter around a point, formatted as `lat,lon` (two numbers). Combine with `radius_km` (default 100 km, capped at 2000). The point+radius is expanded to an enclosing bounding box, so it's a superset of the exact circle. Alternatively pass `lat` and `lon` separately — the shape an asset's `geo.lat`/`geo.lon` hands you. A malformed point returns `400 INVALID_NEAR`; an explicit `bbox` takes precedence over `near`. example: 30.7,32.3 eventsLat: name: lat in: query required: false schema: type: number minimum: -90 maximum: 90 example: 30.7 description: >- Latitude of the proximity point, in [-90,90]. Must be supplied together with `lon` (or use `near=lat,lon` instead). Pairs with `radius_km`. eventsLon: name: lon in: query required: false schema: type: number minimum: -180 maximum: 180 example: 32.3 description: >- Longitude of the proximity point, in [-180,180]. Must be supplied together with `lat` (or use `near=lat,lon`). Alias `lng` is accepted. eventsRadiusKm: name: radius_km in: query required: false schema: type: number minimum: 0 example: 50 description: >- Radius in kilometres for the `near` / `lat`+`lon` proximity point. Defaults to 100 km and is capped at 2000 km so it stays a proximity filter rather than a hemisphere scan. Ignored when no point is given. eventFamily: name: event_family in: query deprecated: true description: >- Deprecated legacy filter. Prefer `category`, which implies Conflict vs CAMEO+. Still accepted for backwards compatibility. schema: $ref: '#/components/schemas/EventFamily' category: name: category in: query description: >- 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](/api-reference/taxonomy). schema: type: string example: Battles example: Battles subcategory: name: subcategory in: query description: >- 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](/api-reference/taxonomy). schema: type: string example: Armed clash example: Armed clash domain: name: domain in: query description: >- Deprecated legacy CAMEO+ domain enum. Prefer `category`/`categories` for new integrations; retained for backwards compatibility. Full list: [Taxonomy & Codes](/api-reference/taxonomy). schema: $ref: '#/components/schemas/Domain' deprecated: true search: name: search in: query description: >- 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. schema: type: string example: attacks on energy infrastructure example: attacks on energy infrastructure hasFatalities: name: has_fatalities in: query description: >- Set `true` for fatality monitoring. v2 intentionally exposes only this boolean fatality filter. schema: type: boolean example: true example: true civilianTargeting: name: civilian_targeting in: query description: >- Filter Conflict-linked evidence by ACLED civilian_targeting. `true` keeps records where civilians are the primary target; `false` excludes those records. schema: type: boolean significanceMin: name: significance_min in: query required: false schema: type: number minimum: 0 maximum: 1 description: Significance minimum filter. Composite 0-1 Event significance score. significanceMax: name: significance_max in: query required: false schema: type: number minimum: 0 maximum: 1 description: Significance maximum filter. Composite 0-1 Event significance score. confidenceMin: name: confidence_min in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Confidence minimum filter. Model confidence for the structured Event record. confidenceMax: name: confidence_max in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Confidence maximum filter. Model confidence for the structured Event record. goldsteinScaleMin: name: goldstein_scale_min in: query required: false schema: type: number minimum: -10 maximum: 10 description: >- Goldstein scale minimum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful. goldsteinScaleMax: name: goldstein_scale_max in: query required: false schema: type: number minimum: -10 maximum: 10 description: >- Goldstein scale maximum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful. goldsteinSeverityMin: name: goldstein_severity_min in: query required: false schema: type: number minimum: 0 maximum: 10 description: >- Goldstein severity minimum filter. Absolute Goldstein intensity, regardless of positive or negative valence. goldsteinSeverityMax: name: goldstein_severity_max in: query required: false schema: type: number minimum: 0 maximum: 10 description: >- Goldstein severity maximum filter. Absolute Goldstein intensity, regardless of positive or negative valence. magnitudeMin: name: magnitude_min in: query required: false schema: type: number minimum: 0 maximum: 10 description: >- Magnitude minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. magnitudeMax: name: magnitude_max in: query required: false schema: type: number minimum: 0 maximum: 10 description: >- Magnitude maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. systemicImportanceMin: name: systemic_importance_min in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Systemic importance minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. systemicImportanceMax: name: systemic_importance_max in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Systemic importance maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. propagationPotentialMin: name: propagation_potential_min in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Propagation potential minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. propagationPotentialMax: name: propagation_potential_max in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Propagation potential maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. marketSensitivityMin: name: market_sensitivity_min in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Market sensitivity minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. marketSensitivityMax: name: market_sensitivity_max in: query required: false schema: type: number minimum: 0 maximum: 1 description: >- Market sensitivity maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores. languages: name: languages in: query description: >- 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. schema: type: string example: en,zh example: en,zh includeImages: name: include_images in: query description: >- 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. schema: type: boolean default: true example: true sort: name: sort in: query description: >- `significance` is the default analyst ranking. Use `recent` when freshness matters more than importance. schema: $ref: '#/components/schemas/Sort' example: significance example: significance limit: name: limit in: query description: Number of records to return. schema: type: integer minimum: 1 maximum: 100 default: 25 example: 25 example: 25 cursor: name: cursor in: query description: Pagination cursor from `pagination.next_cursor`. schema: type: string schemas: PaginatedResponse: type: object properties: success: type: boolean enum: - true pagination: $ref: '#/components/schemas/Pagination' EventCard: type: object properties: id: type: string url: type: string format: uri nullable: true primary_story_url: type: string format: uri nullable: true family: $ref: '#/components/schemas/EventFamily' title: type: string nullable: true summary: type: string nullable: true image_url: type: string format: uri nullable: true description: >- First available top-article sharing image promoted to the Event card. event_date: type: string format: date category: type: string nullable: true subcategory: type: string nullable: true domain: type: string nullable: true event_code: type: string nullable: true geo: $ref: '#/components/schemas/Geo' geo_context: $ref: '#/components/schemas/GeoContext' actors: type: array items: type: object metrics: type: object properties: significance: type: number goldstein_scale: type: number nullable: true description: >- Canonical signed -10 to +10 Goldstein scale. Present for Conflict Events and CAMEO+ POLITICAL Events where meaningful; null for non-political CAMEO+ Events. It is the only public Goldstein metric on Event cards. magnitude: type: number nullable: true description: >- Intensity within the event's own domain, 0-10. Comparable WITHIN a domain only (a conflict 9 and a technology 9 are not the same size) - use `significance` to rank across domains. Four paths: conflict = min(10, 2 + 2*log10(deaths)); hazard, verbal and economic use anchored 0-10 tiers. `null` when no severity observable was found - null means UNKNOWN, not zero, and must never be coerced to 0. CAMEO+ events only. These four are rubric scores, not measurements: a hard registry observable resolves for ~2.2% of events. Treat them as ordinal ranking signals. systemic_importance: type: number nullable: true description: >- How much the wider system depends on the node this event touched: the equal-weighted mean of size, interconnectedness and irreplaceability, following Basel BCBS G-SIB and ECB O-SII practice. It is about the NODE, not the number of countries or people involved. Low base rate. CAMEO+ events only. These four are rubric scores, not measurements: a hard registry observable resolves for ~2.2% of events. Treat them as ordinal ranking signals. propagation_potential: type: number nullable: true description: >- The transmission conditions PRESENT NOW that would let a shock travel: the mean of channel, coupling, breach, primed and (1 - containment), returning 0 when no live channel exists. Adapted from the ERCS barrier model and Rinaldi-Peerenboom-Kelly dependency coupling. NOT a probability, NOT a forecast of follow-on events, and it carries no per-domain prior. CAMEO+ events only. These four are rubric scores, not measurements: a hard registry observable resolves for ~2.2% of events. Treat them as ordinal ranking signals. market_sensitivity: type: number nullable: true description: >- How much market-relevant information the event carries for a reasonable investor: the mean of claim_exposure and economic_bite, returning 0 when nothing traded is exposed. Adapted from the reasonable-investor materiality test (TSC v. Northway; MAR Art. 7(4)). An UNSIGNED ORDINAL RANKING SIGNAL - not a predicted price move, not a probability, not an expected return, and it indicates no direction. CAMEO+ events only. These four are rubric scores, not measurements: a hard registry observable resolves for ~2.2% of events. Treat them as ordinal ranking signals. confidence: type: number nullable: true article_count: type: integer has_fatalities: type: boolean fatalities: type: integer story_refs: type: array items: type: object entity_refs: type: array items: $ref: '#/components/schemas/EntityRef' top_articles: type: array maxItems: 3 items: $ref: '#/components/schemas/Article' civilian_targeting: type: boolean description: True when the Conflict Event has ACLED civilian_targeting populated. civilian_targeting_label: type: string nullable: true description: ACLED civilian_targeting label when available. Sort: type: string enum: - significance - recent default: significance EventFamily: type: string enum: - conflict - cameoplus Domain: type: string enum: - POLITICAL - ECONOMIC - CORPORATE - TECHNOLOGY - INFRASTRUCTURE - HEALTH - DEMOGRAPHIC - INFORMATION - ENVIRONMENT - CRIME Pagination: type: object properties: limit: type: integer cursor: type: string nullable: true next_cursor: type: string nullable: true Geo: type: object properties: country: type: string nullable: true region: type: string nullable: true continent: type: string nullable: true admin1: type: string nullable: true location: type: string nullable: true latitude: type: number nullable: true longitude: type: number nullable: true GeoContext: type: object description: >- Explains broad geography matches. geo is the event/story location; actor_origin_countries explains matches where the requested country, region, or continent came from actor origin instead. properties: location_country: type: string nullable: true actor_origin_countries: type: array items: type: string EntityRef: type: object properties: id: type: string name: type: string type: type: string nullable: true wikipedia_url: type: string format: uri nullable: true 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. Article: type: object properties: id: type: string nullable: true url: type: string format: uri title: type: string nullable: true domain: type: string nullable: true domain_avatar_url: type: string format: uri nullable: true description: Best-effort source-domain avatar/favicon URL for UI rendering. image_url: type: string format: uri nullable: true description: Best-effort source article sharing image from the GDELT GKG layer. article_date: type: string format: date nullable: true rank: type: integer nullable: true role: type: string nullable: true ErrorResponse: type: object properties: success: type: boolean enum: - false error: type: string code: type: string details: type: object description: >- Recoverable validation context when available, such as param, invalid_value, accepted_values, nearest_values, and a corrected example. additionalProperties: true responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````