---
title: "Search Stories"
method: GET
path: "/api/v2/stories"
tags: ["Stories"]
---

# Search Stories

`GET /api/v2/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.

## Query parameters

- `date_start` string, date
- `date_end` string, date
- `country` string
- `region` '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'
- `continent` 'Africa' | 'Asia' | 'Europe' | 'North America' | 'South America' | 'Oceania'
- `admin1` string
- `bbox` string
- `category` string
- `story_category` 'conflict_security' | 'cameoplus_political' | 'cameoplus_crime' | 'cameoplus_economic' | 'cameoplus_corporate' | 'cameoplus_technology' | 'cameoplus_infrastructure' | 'cameoplus_environment' | 'cameoplus_health' | 'cameoplus_demographic' | 'cameoplus_information'
- `event_category` string
- `subcategory` string
- `domain` 'POLITICAL' | 'ECONOMIC' | 'CORPORATE' | 'TECHNOLOGY' | 'INFRASTRUCTURE' | 'HEALTH' | 'DEMOGRAPHIC' | 'INFORMATION' | 'ENVIRONMENT' | 'CRIME'
- `search` string
- `has_events` boolean
- `has_fatalities` boolean
- `civilian_targeting` boolean
- `article_count_min` integer
- `article_count_max` integer
- `languages` string
- `include_images` boolean
- `sort` 'significance' | 'recent'
- `limit` integer
- `cursor` string

## Response `200`

Story cards

- object
  - `success` true
  - `pagination` Pagination
    - `limit` integer
    - `cursor` string, nullable
    - `next_cursor` string, nullable
  - `data` StoryCard[]
    - `id` string
    - `url` string, uri, nullable
    - `title` string, nullable
    - `image_url` string, uri, nullable — First available top-article sharing image promoted to the Story card.
    - `story_date` string, date
    - `category` string, nullable
    - `subcategory` string, nullable
    - `geo` Geo
      - `country` string, nullable
      - `region` string, nullable
      - `continent` string, nullable
      - `admin1` string, nullable
      - `location` string, nullable
      - `latitude` number, nullable
      - `longitude` number, nullable
    - `geo_context` GeoContext — 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.
      - `location_country` string, nullable
      - `actor_origin_countries` string[]
    - `metrics` object
      - `significance` number
      - `article_count` integer
      - `linked_event_count` integer
      - `max_linked_event_significance` number
      - `civilian_targeting_event_count` integer — Number of linked Events with ACLED civilian_targeting populated.
    - `has_events` boolean
    - `has_fatalities` boolean
    - `fatalities` integer
    - `linked_events` object[]
    - `entity_refs` EntityRef[]
      - `id` string
      - `name` string
      - `type` string, nullable
      - `wikipedia_url` string, uri, nullable
      - `image_url` string, uri, nullable — Best-effort Wikipedia thumbnail URL for UI rendering.
      - `avatar_url` string, uri, nullable — Best-effort compact avatar URL, usually the same as image_url.
    - `top_articles` Article[]
      - `id` string, nullable
      - `url` string, uri
      - `title` string, nullable
      - `domain` string, nullable
      - `domain_avatar_url` string, uri, nullable — Best-effort source-domain avatar/favicon URL for UI rendering.
      - `image_url` string, uri, nullable — Best-effort source article sharing image from the GDELT GKG layer.
      - `article_date` string, date, nullable
      - `rank` integer, nullable
      - `role` string, nullable
    - `has_civilian_targeting` boolean — True when linked Conflict Events include civilian targeting evidence.
  - `sort` 'significance' | 'recent'

---

[API](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2.md) · [All operations](https://skmtc.net/gdeltcloud/apis/gdelt-cloud-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gdeltcloud/gdelt-cloud-api-v2/versions/01aaa6255180/schema)