> ## 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 Stories > Return dashboard-ready Story rollups by date, geography, category, or subcategory. Summaries use broad result coverage and linked-Event aggregation. Use category/subcategory to filter by linked Event taxonomy. For group_by=category or group_by=subcategory, buckets are linked-Event taxonomy buckets, so narrative-only Stories are not counted in those taxonomy buckets. ## OpenAPI ````yaml /api-reference/openapi-v2.json get /api/v2/stories/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/stories/summary: get: tags: - Stories summary: Summarize Stories description: >- Return dashboard-ready Story rollups by date, geography, category, or subcategory. Summaries use broad result coverage and linked-Event aggregation. Use category/subcategory to filter by linked Event taxonomy. For group_by=category or group_by=subcategory, buckets are linked-Event taxonomy buckets, so narrative-only Stories are not counted in those taxonomy buckets. operationId: summarize-stories-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' - name: bbox in: query required: false schema: type: string description: >- 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. example: 24,49,30,57 - $ref: '#/components/parameters/category' - $ref: '#/components/parameters/storyCategory' - $ref: '#/components/parameters/eventCategory' - $ref: '#/components/parameters/subcategory' - $ref: '#/components/parameters/domain' - $ref: '#/components/parameters/hasEvents' - $ref: '#/components/parameters/hasFatalities' - $ref: '#/components/parameters/civilianTargeting' - $ref: '#/components/parameters/articleCountMin' - $ref: '#/components/parameters/articleCountMax' - name: languages in: query description: >- Filter to Stories 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: Story summary buckets content: application/json: schema: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/StorySummaryBucket' examples: summary: value: success: true group_by: country data: - key: Japan group_by: country story_count: 8 article_count: 44 avg_article_count: 5.5 max_article_count: 13 stories_with_events: 6 stories_with_fatalities: 0 fatalities: 0 avg_significance: 0.51 max_significance: 0.83 min_significance: 0.19 linked_event_count: 11 avg_linked_event_count: 1.38 max_linked_event_count: 4 avg_linked_event_significance: 0.47 avg_linked_event_goldstein_scale: -1.9 avg_linked_event_magnitude: 0.38 avg_linked_event_systemic_importance: 0.33 avg_linked_event_propagation_potential: 0.27 avg_linked_event_market_sensitivity: 0.29 avg_linked_event_confidence: 0.79 avg_recency_score: 0.64 metrics: significance: avg: 0.51 max: 0.83 min: 0.19 article_count: total: 44 avg: 5.5 max: 13 linked_events: count: 11 avg_per_story: 1.38 max_per_story: 4 significance: avg: 0.47 max: 0.78 goldstein_scale: avg: -1.9 max: 4.2 avg_severity: 2.6 cameoplus: magnitude: avg: 0.38 max: 0.7 systemic_importance: avg: 0.33 max: 0.62 propagation_potential: avg: 0.27 max: 0.55 market_sensitivity: avg: 0.29 max: 0.61 confidence: avg: 0.79 max: 0.94 recency_score: avg: 0.64 fatalities: stories: 0 rate: 0 total: 0 metric_stats: significance: avg: 0.51 max: 0.83 min: 0.19 security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl "https://gdeltcloud.com/api/v2/stories/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 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 storyCategory: name: story_category in: query required: false schema: type: string example: conflict_security enum: - conflict_security - cameoplus_political - cameoplus_crime - cameoplus_economic - cameoplus_corporate - cameoplus_technology - cameoplus_infrastructure - cameoplus_environment - cameoplus_health - cameoplus_demographic - cameoplus_information description: >- Legacy Story-cluster category filter such as `conflict_security` or `cameoplus_infrastructure`. Prefer linked Event `category`/`subcategory` for product taxonomy filtering. eventCategory: name: event_category in: query required: false deprecated: true schema: type: string description: >- Deprecated alias for `category` on Story endpoints. Prefer `category=Battles` or a CAMEO+ domain such as `category=CRIME`. Full list: [Taxonomy & Codes](/api-reference/taxonomy). 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 hasEvents: name: has_events in: query description: >- For Stories, set `true` to require linked structured Events or `false` for Stories without linked Events. schema: type: boolean example: true example: 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 articleCountMin: name: article_count_min in: query description: Minimum Story article count. schema: type: integer minimum: 0 example: 2 example: 2 articleCountMax: name: article_count_max in: query description: Maximum Story article count. schema: type: integer minimum: 0 example: 25 example: 25 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: StorySummaryBucket: type: object description: >- One grouped Story summary bucket. linked_event_count is a Story-to-Event link aggregate, not a distinct Event total. story_only_count is derived as story_count minus stories_with_events. When group_by is category or subcategory, key is a linked Event taxonomy value such as Battles or Government regains territory. properties: key: type: string nullable: true group_by: type: string story_count: type: integer article_count: type: integer avg_article_count: type: number max_article_count: type: integer stories_with_events: type: integer linked_event_count: type: integer description: >- Total Story-to-Event links in this Story bucket, not a distinct Event total. avg_linked_event_count: type: number max_linked_event_count: type: integer stories_with_fatalities: type: integer fatalities: type: integer fatality_story_rate: type: number avg_significance: type: number max_significance: type: number min_significance: type: number metrics: type: object description: >- Nested aggregate statistics for Story significance inputs and linked Event metrics. additionalProperties: true example: significance: avg: 0.5 max: 0.88 min: 0.12 article_count: total: 25 avg: 5 min: 2 max: 11 linked_events: count: total: 7 avg: 1.4 min: 0 max: 3 stories_with_events: 4 story_only_count: 1 significance: avg: 0.62 min: 0.18 max: 0.94 goldstein_scale: avg: -3.2 min: -7.5 max: 1.5 avg_severity: 3.8 goldstein_severity: avg: 3.8 min: 0.8 max: 7.5 magnitude: avg: 5.5 min: 1.1 max: 8.4 systemic_importance: avg: 0.44 min: 0.12 max: 0.77 propagation_potential: avg: 0.41 min: 0.09 max: 0.72 market_sensitivity: avg: 0.39 min: 0.04 max: 0.68 confidence: avg: 0.81 min: 0.51 max: 0.96 recency_score: avg: 1 fatalities: stories: 1 rate: 0.2 total: 2 metric_stats: type: object description: >- Alias of metrics for clients that prefer an explicit statistical field name. additionalProperties: true min_article_count: type: integer story_only_count: type: integer description: Stories in the bucket with no linked structured Events. min_linked_event_count: type: integer avg_linked_event_significance: type: number nullable: true min_linked_event_significance: type: number nullable: true max_linked_event_significance: type: number nullable: true avg_linked_event_goldstein_scale: type: number nullable: true min_linked_event_goldstein_scale: type: number nullable: true max_linked_event_goldstein_scale: type: number nullable: true avg_linked_event_goldstein_severity: type: number nullable: true min_linked_event_goldstein_severity: type: number nullable: true max_linked_event_goldstein_severity: type: number nullable: true avg_linked_event_magnitude: type: number nullable: true min_linked_event_magnitude: type: number nullable: true max_linked_event_magnitude: type: number nullable: true avg_linked_event_systemic_importance: type: number nullable: true min_linked_event_systemic_importance: type: number nullable: true max_linked_event_systemic_importance: type: number nullable: true avg_linked_event_propagation_potential: type: number nullable: true min_linked_event_propagation_potential: type: number nullable: true max_linked_event_propagation_potential: type: number nullable: true avg_linked_event_market_sensitivity: type: number nullable: true min_linked_event_market_sensitivity: type: number nullable: true max_linked_event_market_sensitivity: type: number nullable: true avg_linked_event_confidence: type: number nullable: true min_linked_event_confidence: type: number nullable: true max_linked_event_confidence: type: number nullable: true GroupBy: type: string enum: - date - country - region - continent - category - subcategory 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_...`.' ````