> ## 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.

# Recommended Usage Cookbook

> Field-tested query recipes and defaults for the v2 API — surface selection, monitoring patterns, semantic search, and drilldowns.

## Choosing a surface

* **Events** — structured incidents: actors, event `category`/`subcategory`, fatalities, Goldstein scale, and event-level metrics.
* **Stories** — clustered narratives with top article evidence; best for discovery of emerging topics.
* **Summaries** (`/events/summary`, `/stories/summary`) — dashboard totals and trend charts. Drill down into Events or Stories with the same filters.
* **Entities** — people and organizations, with linked Stories/Events. Resolve a name first via [`/entities/resolve`](/api-reference/concepts#finding-an-entity-when-you-dont-know-the-exact-name).
* **Energy** — GEM assets and owners; resolve an owner, then pull its cross-tracker portfolio.
* **Facilities** — the unified physical-asset directory (energy assets + ports + AI data centers); filter by `type`/`class`/`near`, or pivot from an `owner_entity_id` to its whole portfolio.

## Defaults worth adopting

* Use `limit=10` for exploratory / API Playground requests, then raise it when you need more rows.
* Use `sort=significance` for monitoring and dashboards; `sort=recent` when freshness matters more than importance.
* Use plain-English geography in apps, e.g. `country=United States`.
* When writing code, pass parameters through your HTTP client's `params` / `URLSearchParams` rather than hand-building URLs — clients encode `United States` correctly, and the API decodes both `%20` and `+`.
* Omit dates for the past 24 hours. Explicit `date_start`/`date_end` filter by event or story date and the window must be **30 days or less**.
* Start broad, then narrow with geography, `category`, `subcategory`, date windows, and semantic `search`.
* `search` is true semantic retrieval on **list endpoints only**: v2 embeds the query, applies the structured filters as the candidate set, and ranks by cosine similarity. Summary endpoints do not accept `search`.
* Discover `admin1` values per-country via `/api/v2/geo/admin1?country=...` before using them.
* Treat inline `top_articles` as an evidence preview; use `/api/v2/stories/{story_id}/articles` for the full paginated source list.

<Note>
  Metric filters use canonical response-field names. `significance` and `confidence` apply across families;
  `magnitude`, `systemic_importance`, `propagation_potential`, and `market_sensitivity` only match CAMEO+
  Events with those scores; `goldstein_scale`/`goldstein_severity` match Conflict and CAMEO+ `POLITICAL`
  Events. See the full list in [Taxonomy & Codes](/api-reference/taxonomy#event-metric-filters).
</Note>

## Country, region, or continent monitoring

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?country=United%20States&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/stories?continent=Asia&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Infrastructure events

Use CAMEO+ `category=INFRASTRUCTURE` as the canonical pattern:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=INFRASTRUCTURE&country=United%20States&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

For high-propagation infrastructure incidents:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=INFRASTRUCTURE&propagation_potential_min=0.6&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

For high-significance Events across families:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?significance_min=0.7&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Semantic event search

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?search=attacks%20on%20energy%20infrastructure&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Protests today or recently

For a current list:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=Protests&subcategory=Peaceful%20protest&country=India&date_start=2026-04-17&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

For a daily dashboard trend:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events/summary?category=Protests&subcategory=Peaceful%20protest&country=India&group_by=date&date_start=2026-04-11&date_end=2026-04-17" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## New data center projects in Asia

Use Stories first because this is a narrative discovery task. Keep `article_count_min=1` for emerging-project discovery; raise it only when you want more source volume.

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/stories?continent=Asia&search=new%20data%20center%20projects&article_count_min=1&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

Then use Events if you need structured infrastructure event records:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=INFRASTRUCTURE&continent=Asia&search=data%20center%20projects&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Fatal conflict monitoring

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=Explosions%2FRemote%20violence&subcategory=Air%2Fdrone%20strike&has_fatalities=true&country=Lebanon&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Admin1 drilldown

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/geo/admin1?country=United%20States" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?country=United%20States&admin1=District%20of%20Columbia&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Bounding box drilldown

When `country` or `admin1` is too coarse — straits, ports, basins, border zones, custom viewports — filter directly on Event coordinates with `bbox=lat_min,lon_min,lat_max,lon_max`:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?bbox=11.5,42.5,13.5,44.5&category=Explosions%2FRemote%20violence&subcategory=Air%2Fdrone%20strike&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/stories/summary?bbox=26,55,30,58&group_by=date&date_start=2026-04-11&date_end=2026-04-17" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

Combine with `country` when you want events in a specific area of a specific country:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/events?country=United%20States&bbox=38,-77.2,39,-76.8&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Story articles

Story list and detail responses return only the top 3 inline articles. Use the articles endpoint for the full source set:

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/stories/{story_id}/articles?limit=25" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

```bash theme={null}
curl "https://gdeltcloud.com/api/v2/stories/{story_id}/articles?limit=25&cursor={next_cursor}" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
```

## Resolve an entity, then fan out

`/api/v2/entities/resolve` is the fuzzy "find the entity" step — start there with a name, pick the best `entity_id`, then call the surfaces you need with that shared id (profile, exposure, filings, screening). See [Entity resolution](/api-reference/concepts#entity-aliases-and-resolution).