> ## 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. # Summarize Events > Return dashboard-ready Event rollups by date, geography, category, or subcategory. Use group_by=subcategory under a parent category such as Battles to discover scoped sub-event buckets like Government regains territory, then reuse category+subcategory on /api/v2/events to fetch instances. Summaries use the same broad result coverage as Event lists and are designed for discovery before drilling into Events. ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/events/summary 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/summary: get: tags: - Events summary: Summarize Events description: >- Return dashboard-ready Event rollups by date, geography, category, or subcategory. Use group_by=subcategory under a parent category such as Battles to discover scoped sub-event buckets like Government regains territory, then reuse category+subcategory on /api/v2/events to fetch instances. Summaries use the same broad result coverage as Event lists and are designed for discovery before drilling into Events. operationId: summarize-events-v2 parameters: - $ref: '#/components/parameters/groupBy' - $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/eventFamily' - $ref: '#/components/parameters/category' - $ref: '#/components/parameters/subcategory' - $ref: '#/components/parameters/domain' - $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' - name: languages in: query description: >- Filter to Events with at least one linked article in these source (origin) languages. Comma-separated ISO codes (`en`, `zh`, `ar`, …), OR'd; alias `language` accepted. Caveat: honored for every non-date `group_by`, and for a `group_by=date` query that also carries another qualifying filter — but IGNORED (and reported under `applied_filters.ignored`) on the lightweight `group_by=date` fast path with no other filter. schema: type: string example: en,zh example: en,zh - $ref: '#/components/parameters/limitSummary' responses: '200': description: Event summary buckets content: application/json: schema: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/EventSummaryBucket' examples: summary: value: success: true group_by: date data: - key: '2026-04-15' group_by: date event_count: 12 conflict_event_count: 7 cameoplus_event_count: 5 fatality_event_count: 2 fatality_event_rate: 0.167 fatalities: 6 article_count: 38 avg_article_count: 3.17 max_article_count: 9 avg_significance: 0.42 max_significance: 0.86 min_significance: 0.12 avg_goldstein_scale: -3.8 min_goldstein_scale: -9.5 max_goldstein_scale: 3.4 avg_goldstein_severity: 4.1 avg_magnitude: 0.44 avg_systemic_importance: 0.36 avg_propagation_potential: 0.31 avg_market_sensitivity: 0.18 avg_confidence: 0.74 metrics: significance: avg: 0.42 max: 0.86 min: 0.12 goldstein_scale: avg: -3.8 min: -9.5 max: 3.4 avg_severity: 4.1 cameoplus: magnitude: avg: 0.44 max: 0.72 systemic_importance: avg: 0.36 max: 0.68 propagation_potential: avg: 0.31 max: 0.59 market_sensitivity: avg: 0.18 max: 0.41 confidence: avg: 0.74 max: 0.91 article_count: total: 38 avg: 3.17 max: 9 fatalities: events: 2 rate: 0.167 total: 6 metric_stats: significance: avg: 0.42 max: 0.86 min: 0.12 security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl "https://gdeltcloud.com/api/v2/events/summary" \ -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" components: parameters: groupBy: name: group_by in: query description: >- Summary grouping dimension. For Events, category is Conflict event type or CAMEO+ domain and subcategory is Conflict sub-event type or CAMEO+ event description/code. For Stories, category/subcategory grouping uses linked Event taxonomy; use story_category only as a Story-cluster filter. schema: $ref: '#/components/schemas/GroupBy' example: date example: date 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 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 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. limitSummary: name: limit in: query description: Number of summary buckets to return. schema: type: integer minimum: 1 maximum: 500 default: 50 example: 50 example: 50 schemas: EventSummaryBucket: type: object description: >- One grouped Event summary bucket. Includes legacy flat fields plus nested metrics/metric_stats with min/avg/max aggregate statistics for the generated inputs used in Event significance scoring. 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. properties: key: type: string nullable: true group_by: type: string event_count: type: integer conflict_event_count: type: integer cameoplus_event_count: type: integer fatality_event_count: type: integer fatalities: type: integer fatality_event_rate: type: number country_count: type: integer region_count: type: integer article_count: type: integer avg_article_count: type: number max_article_count: type: integer avg_significance: type: number max_significance: type: number min_significance: type: number avg_goldstein_scale: type: number nullable: true metrics: type: object description: >- Nested aggregate statistics for significance and its generated input metrics. additionalProperties: true example: significance: avg: 0.42 max: 0.91 min: 0.05 goldstein_scale: avg: -3.8 min: -8 max: 2 avg_severity: 4.2 goldstein_severity: avg: 4.2 min: 0.5 max: 8 cameoplus: magnitude: avg: 6.1 min: 1.2 max: 9 systemic_importance: avg: 0.52 min: 0.11 max: 0.9 propagation_potential: avg: 0.47 min: 0.07 max: 0.81 market_sensitivity: avg: 0.31 min: 0.03 max: 0.75 confidence: avg: 0.83 min: 0.44 max: 0.98 article_count: total: 40 avg: 3.333 min: 1 max: 12 fatalities: events: 2 rate: 0.1667 total: 6 metric_stats: type: object description: >- Alias of metrics for clients that prefer an explicit statistical field name. additionalProperties: true min_article_count: type: integer min_goldstein_scale: type: number nullable: true max_goldstein_scale: type: number nullable: true avg_goldstein_severity: type: number nullable: true min_goldstein_severity: type: number nullable: true max_goldstein_severity: type: number nullable: true avg_magnitude: type: number nullable: true min_magnitude: type: number nullable: true max_magnitude: type: number nullable: true avg_systemic_importance: type: number nullable: true min_systemic_importance: type: number nullable: true max_systemic_importance: type: number nullable: true avg_propagation_potential: type: number nullable: true min_propagation_potential: type: number nullable: true max_propagation_potential: type: number nullable: true avg_market_sensitivity: type: number nullable: true min_market_sensitivity: type: number nullable: true max_market_sensitivity: type: number nullable: true avg_confidence: type: number nullable: true min_confidence: type: number nullable: true max_confidence: type: number nullable: true GroupBy: type: string enum: - date - country - region - continent - category - subcategory EventFamily: type: string enum: - conflict - cameoplus Domain: type: string enum: - POLITICAL - ECONOMIC - CORPORATE - TECHNOLOGY - INFRASTRUCTURE - HEALTH - DEMOGRAPHIC - INFORMATION - ENVIRONMENT - CRIME securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````