---
title: "Search Events"
method: GET
path: "/api/v2/events"
tags: ["Events"]
---

# Search Events

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

## 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
- `near` string
- `lat` number
- `lon` number
- `radius_km` number
- `event_family` 'conflict' | 'cameoplus'
- `category` string
- `subcategory` string
- `domain` 'POLITICAL' | 'ECONOMIC' | 'CORPORATE' | 'TECHNOLOGY' | 'INFRASTRUCTURE' | 'HEALTH' | 'DEMOGRAPHIC' | 'INFORMATION' | 'ENVIRONMENT' | 'CRIME'
- `search` string
- `has_fatalities` boolean
- `civilian_targeting` boolean
- `significance_min` number
- `significance_max` number
- `confidence_min` number
- `confidence_max` number
- `goldstein_scale_min` number
- `goldstein_scale_max` number
- `goldstein_severity_min` number
- `goldstein_severity_max` number
- `magnitude_min` number
- `magnitude_max` number
- `systemic_importance_min` number
- `systemic_importance_max` number
- `propagation_potential_min` number
- `propagation_potential_max` number
- `market_sensitivity_min` number
- `market_sensitivity_max` number
- `languages` string
- `include_images` boolean
- `sort` 'significance' | 'recent'
- `limit` integer
- `cursor` string

## Response `200`

Event cards

- object
  - `success` true
  - `pagination` Pagination
    - `limit` integer
    - `cursor` string, nullable
    - `next_cursor` string, nullable
  - `data` EventCard[]
    - `id` string
    - `url` string, uri, nullable
    - `primary_story_url` string, uri, nullable
    - `family` 'conflict' | 'cameoplus'
    - `title` string, nullable
    - `summary` string, nullable
    - `image_url` string, uri, nullable — First available top-article sharing image promoted to the Event card.
    - `event_date` string, date
    - `category` string, nullable
    - `subcategory` string, nullable
    - `domain` string, nullable
    - `event_code` 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[]
    - `actors` object[]
    - `metrics` object
      - `significance` number
      - `goldstein_scale` number, nullable — 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` number, nullable
      - `systemic_importance` number, nullable
      - `propagation_potential` number, nullable
      - `market_sensitivity` number, nullable
      - `confidence` number, nullable
      - `article_count` integer
    - `has_fatalities` boolean
    - `fatalities` integer
    - `story_refs` 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
    - `civilian_targeting` boolean — True when the Conflict Event has ACLED civilian_targeting populated.
    - `civilian_targeting_label` string, nullable — ACLED civilian_targeting label when available.
  - `sort` 'significance' | 'recent'

## Other responses

- `400` — Invalid request
- `401` — Missing or invalid API key

---

[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/revisions/01aaa6255180/schema)