---
title: "Search Entities"
method: GET
path: "/api/v2/entities"
tags: ["Entities"]
---

# Search Entities

`GET /api/v2/entities`

Discover linked people and organizations that connect to Stories and Events. Entity taxonomy filters operate on linked Story/Event evidence.

## Query parameters

- `search` string
- `type` 'person' | 'organization'
- `date_start` string, date
- `date_end` string, date
- `event_family` 'conflict' | 'cameoplus'
- `category` string
- `subcategory` string
- `domain` 'POLITICAL' | 'ECONOMIC' | 'CORPORATE' | 'TECHNOLOGY' | 'INFRASTRUCTURE' | 'HEALTH' | 'DEMOGRAPHIC' | 'INFORMATION' | 'ENVIRONMENT' | 'CRIME'
- `has_fatalities` boolean
- `civilian_targeting` boolean
- `sort` 'significance' | 'recent'
- `limit` integer
- `cursor` string

## Response `200`

Entity cards

- object
  - `success` true
  - `pagination` Pagination
    - `limit` integer
    - `cursor` string, nullable
    - `next_cursor` string, nullable
  - `data` EntityCard[]
    - `id` string
    - `url` string, uri, nullable
    - `name` string — Canonical display name — the most-mentioned raw_name variant pointing at this Wikipedia URL.
    - `type` 'person' | 'organization', nullable
    - `wikipedia_url` string, uri, nullable
    - `latest_date` string, date, nullable — Most recent date the Entity appeared in a Story or Event within the requested window.
    - `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.
    - `wikipedia` object, nullable — Compact Wikipedia enrichment when available, including thumbnail_url, description, page_url, and summary on detail responses.
    - `metrics` object — Aggregated activity counts over the requested window, summed across all raw_name variants that map to this Wikipedia URL.
      - `article_count` integer — Total articles in matched Stories and Events mentioning the entity.
      - `story_count` integer — Distinct GDELT Cloud Stories (cluster_ids) the entity appeared in.
      - `event_count` integer — Distinct coded Events (Conflict + CAMEO+) linked to the entity.
    - `story_refs` object[]
    - `event_refs` object[]
    - `entity_tone` object, nullable — Present on Entity detail when include_tone=true and the caller is allowed to access preview tone metadata. tone_status may be scored, reviewable, partial, or not_available.
      - `tone_status` 'scored' | 'reviewable' | 'partial' | 'not_available'
      - `coverage` object
      - `latest_series` object[]
      - `analytics_url` string, nullable
      - `methodology` object

---

[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)