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

# Entity Interactions — who it acts on, and who acts on it

> Counterparts read from the ACTOR slots of coded Events: `acts_on` lists who the entity acted on (it is the source actor), `acted_on_by` who acted on it (it is the target actor), each with the Event count, the most frequent category and up to three sample Events. `places` says where those Events happened and `recent` lists the newest. This is not coverage: `entity=` on `/api/v2/events` returns Events in Stories that MENTION the entity, while this endpoint returns Events in which the entity is a party. `{entity_id}` accepts a spine `e_` id, a `wiki:`/`llm:` id, a Wikipedia URL or a name; aliases merged into the entity are read with it. A counterpart coded without an entity id (a role such as "investors") is kept with `entity_id: null` unless `resolved_only=true`. Served from settled partitions; `meta.coverage` names every withheld date.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/entities/{entity_id}/interactions
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
security:
  - ApiKeyAuth: []
tags:
  - name: Events
    description: Coded CAMEO+ / conflict events — search, fetch, and summarize.
  - name: Stories
    description: Clustered narratives (stories) and their articles.
  - name: Situations
    description: >-
      One real-world occurrence as the Stories and coded Events that belong to
      it — stored, adjudicated membership (`meta.situation_source: curated`) or
      a walked neighbourhood around a Story. Discovery, detail, four
      independently paged member lists, and the only write on the core surface
      (5 QU with an Idempotency-Key).
  - name: Entities
    description: >-
      People & organizations — resolve a name to an entity, then fetch its
      profile and tone. Also the publication activity journal
      (/api/v2/activity): observed evidence of what was published about
      identities and records — committed batches only, cursor-paged, never
      source intake.
  - name: Unified Search
    description: >-
      One fuzzy lookup across every id-space — start here with a name, take the
      entity id, then reuse it on every other surface. This is the resolver the
      rest of the API assumes you called first.
  - name: Media Intelligence
    description: >-
      Press-coverage tone over time and share of voice against a peer set.
      Requires the `can_use_tone` / `can_use_share_of_voice` entitlement; social
      signal is an admin-only preview.
  - name: Facilities
    description: >-
      Unified physical-asset directory — GEM energy assets, World Port Index
      ports and Epoch AI data centers on one keyed surface, resolved to spine
      owners. Requires the `can_use_facilities` entitlement.
  - name: Monitors
    description: >-
      Organization-shared scheduled checks over the Core API, with email and
      signed-webhook delivery. Monitor execution does not consume query units.
  - name: Saved Queries
    description: >-
      Reusable validated query recipes with private or explicit workspace
      sharing.
  - name: Geography
    description: >-
      Country context and admin-1 geography: /api/v2/countries (publication
      activity, reporting counts, dated economic and resource fundamentals,
      facility and office inventories, directory mode over every registered
      country) and admin-1 lookups.
  - name: Government
    description: >-
      US federal awards (USAspending) and foreign-influence registrations (DOJ
      NSD FARA), resolved onto the entity spine. Requires the `can_use_gov`
      entitlement.
  - name: Political Offices
    description: >-
      Public political offices and who holds them — legislatures, cabinets,
      heads of state, courts and IGO posts, with the office start/end dates the
      publisher states (valid time), resolved onto the entity spine. Actor
      context for geopolitical analysis; NOT a PEP or sanctions-screening tool.
      Requires the `can_use_offices` entitlement.
  - name: Filings
    description: >-
      SEC EDGAR filings, XBRL financials, and relations extracted from filing
      text. Requires the `can_use_filings` entitlement.
  - name: Reference Data
    description: >-
      The GLEIF Global LEI Index — legal-entity reference data, consolidation
      relationships, and LEI↔ISIN mappings. Requires the `can_use_gleif`
      entitlement.
  - name: Energy
    description: Global Energy Monitor assets + ownership registry.
  - name: AI Compute
    description: >-
      Epoch AI datasets — models, hardware, data centers, companies and chip
      sales. Requires the `can_use_epoch_ai` entitlement.
  - name: Macro Finance
    description: >-
      FRED economic time series — catalog, point-in-time observations and
      releases. Requires the `can_use_macro` entitlement.
  - name: Screening and Reference
    description: >-
      Restricted-party lists, name screening and ownership-chain exposure.
      Requires the `can_use_screening` / `can_use_exposure` entitlement.
      Analytical coverage, not an audit-grade compliance control.
  - name: China
    description: >-
      China overseas development finance (AidData GCDF). Requires the
      `can_use_china` entitlement.
  - name: Maritime
    description: >-
      AIS-derived vessel flow — chokepoint transits, last-known vessel
      positions, dwell and AIS-dark gaps. Terrestrial AIS only, so coverage
      thins in open ocean. Requires the `can_use_maritime` entitlement.
  - name: Atlas Intelligence
    description: >-
      Geopolitical-risk and posture indices computed from GDELT Cloud’s own
      coded events, normalized to each place’s own frozen baseline.
  - name: Natural Resources
    description: >-
      USGS mineral production, reserves and qualified country statistics,
      composed with the physical Facilities inventory.
  - name: Briefs
    description: Source-backed monitoring briefs.
  - name: Meta
    description: >-
      Machine-readable discovery: the value vocabularies, the endpoint
      contracts, and the query-unit cost model. Unmetered, so a client can check
      before it spends.
paths:
  /api/v2/entities/{entity_id}/interactions:
    get:
      tags:
        - Entities
      summary: Entity Interactions — who it acts on, and who acts on it
      description: >-
        Counterparts read from the ACTOR slots of coded Events: `acts_on` lists
        who the entity acted on (it is the source actor), `acted_on_by` who
        acted on it (it is the target actor), each with the Event count, the
        most frequent category and up to three sample Events. `places` says
        where those Events happened and `recent` lists the newest. This is not
        coverage: `entity=` on `/api/v2/events` returns Events in Stories that
        MENTION the entity, while this endpoint returns Events in which the
        entity is a party. `{entity_id}` accepts a spine `e_` id, a
        `wiki:`/`llm:` id, a Wikipedia URL or a name; aliases merged into the
        entity are read with it. A counterpart coded without an entity id (a
        role such as "investors") is kept with `entity_id: null` unless
        `resolved_only=true`. Served from settled partitions; `meta.coverage`
        names every withheld date.
      operationId: get-entity-interactions-v2
      parameters:
        - name: entity_id
          in: path
          required: true
          schema:
            type: string
          description: The entity id.
        - name: date_start
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Inclusive first Event date (YYYY-MM-DD). With `date_end`, a literal
            window of at most 30 days.
          example: '2026-11-01'
        - name: date_end
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Inclusive last Event date (YYYY-MM-DD).
          example: '2026-11-20'
        - name: days
          in: query
          required: false
          schema:
            type: string
            default: 30
          description: >-
            Calendar-day window ending today (max 30). A window whose last day
            is not yet served slides to the newest served day;
            `meta.window_adjustment` says so.
          example: '30'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
          description: >-
            Counterparts to return in EACH direction (`acts_on`, `acted_on_by`).
            Default 10, max 50.
          example: '10'
        - name: resolved_only
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: >-
            Drop counterparts the coder named without an entity id (roles such
            as "investors"). Default false.
          example: 'true'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityInteractionsResponse'
              examples:
                default:
                  summary: Who it acts on, last 30 days
                  value:
                    success: true
                    data: {}
        '400':
          description: Invalid or unsupported parameter (see `code` and `details`)
        '401':
          description: Missing or invalid API key
        '403':
          description: Plan does not include this surface
        '404':
          description: Not found `ENTITY_NOT_FOUND` — The entity id does not resolve.
        '410':
          description: >-
            `ENTITY_RETIRED` — The entity id names a retired registry row that
            is not one entity: a dataset cell naming several organisations
            (`details.reason: non_atomic_cell`), an aggregate label
            (`aggregate_cell`), or a concept or place name from a filing
            (`concept`, whose `members` is always empty). `GET
            /api/v2/entities/{entity_id}` and its sub-routes answer 410; the
            same id in `entity=`, `target_ids=` (with `target_type=entity`), a
            `*_entity=` role param, `involved_entity=` or another entity filter
            answers 400. An id merged into a retired row is retired too.
            `details.members` lists the separate entities the cell names as `{
            entity_id, name }`, with `entity_id` null where a member has no id;
            it is empty until they are listed.
        '429':
          description: Quota or rate limit exceeded
        '500':
          description: Server error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EntityInteractionsResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        entity:
          type: object
          properties:
            entity_id:
              type: string
            name:
              type: string
              nullable: true
            resolved_from:
              type: string
            entity_family:
              type: array
              items:
                type: string
          required:
            - entity_id
            - name
            - resolved_from
            - entity_family
        data:
          type: object
          properties:
            totals:
              type: object
              properties:
                events:
                  type: number
                as_source:
                  type: number
                as_target:
                  type: number
              required:
                - events
                - as_source
                - as_target
            acts_on:
              type: array
              items:
                type: object
                properties:
                  entity_id:
                    type: string
                    nullable: true
                  name:
                    type: string
                  country_iso3:
                    type: string
                    nullable: true
                  events:
                    type: number
                  top_category:
                    type: string
                    nullable: true
                  top_subcategory:
                    type: string
                    nullable: true
                  last_event_date:
                    type: string
                  sample_events:
                    type: array
                    items:
                      type: object
                      properties:
                        event_uid:
                          type: string
                        event_date:
                          type: string
                        title:
                          type: string
                        category:
                          type: string
                          nullable: true
                      required:
                        - event_uid
                        - event_date
                        - title
                        - category
                required:
                  - entity_id
                  - name
                  - country_iso3
                  - events
                  - top_category
                  - top_subcategory
                  - last_event_date
                  - sample_events
            acted_on_by:
              type: array
              items:
                type: object
                properties:
                  entity_id:
                    type: string
                    nullable: true
                  name:
                    type: string
                  country_iso3:
                    type: string
                    nullable: true
                  events:
                    type: number
                  top_category:
                    type: string
                    nullable: true
                  top_subcategory:
                    type: string
                    nullable: true
                  last_event_date:
                    type: string
                  sample_events:
                    type: array
                    items:
                      type: object
                      properties:
                        event_uid:
                          type: string
                        event_date:
                          type: string
                        title:
                          type: string
                        category:
                          type: string
                          nullable: true
                      required:
                        - event_uid
                        - event_date
                        - title
                        - category
                required:
                  - entity_id
                  - name
                  - country_iso3
                  - events
                  - top_category
                  - top_subcategory
                  - last_event_date
                  - sample_events
            places:
              type: array
              items:
                type: object
                properties:
                  country_iso3:
                    type: string
                  events:
                    type: number
                  as_source:
                    type: number
                  as_target:
                    type: number
                  latitude:
                    type: number
                    nullable: true
                  longitude:
                    type: number
                    nullable: true
                required:
                  - country_iso3
                  - events
                  - as_source
                  - as_target
                  - latitude
                  - longitude
            categories:
              type: array
              items:
                type: object
                properties:
                  category:
                    type: string
                  events:
                    type: number
                required:
                  - category
                  - events
            recent:
              type: array
              items:
                type: object
                properties:
                  event_uid:
                    type: string
                  event_date:
                    type: string
                  title:
                    type: string
                  category:
                    type: string
                    nullable: true
                  role:
                    type: string
                    enum:
                      - source
                      - target
                      - both
                  subcategory:
                    type: string
                    nullable: true
                  significance:
                    type: number
                    nullable: true
                  country_iso3:
                    type: string
                    nullable: true
                  counterpart_entity_id:
                    type: string
                    nullable: true
                  counterpart_name:
                    type: string
                    nullable: true
                required:
                  - event_uid
                  - event_date
                  - title
                  - category
                  - role
                  - subcategory
                  - significance
                  - country_iso3
                  - counterpart_entity_id
                  - counterpart_name
          required:
            - totals
            - acts_on
            - acted_on_by
            - places
            - categories
            - recent
        meta:
          type: object
          properties:
            query_window:
              type: object
              properties:
                date_start:
                  type: string
                date_end:
                  type: string
              required:
                - date_start
                - date_end
            window_adjustment:
              nullable: true
            coverage:
              type: object
              properties:
                served_dates:
                  type: array
                  items:
                    type: string
                missing_dates:
                  type: array
                  items:
                    type: object
                    properties:
                      date:
                        type: string
                      reason:
                        type: string
                      retryable:
                        type: boolean
                    required:
                      - date
                      - reason
                      - retryable
                awaiting_dates:
                  type: array
                  items:
                    type: string
                window_complete:
                  type: boolean
              required:
                - served_dates
                - missing_dates
                - awaiting_dates
                - window_complete
            as_of:
              type: string
              nullable: true
            row_source:
              type: string
              enum:
                - settled
            truncated:
              type: boolean
          required:
            - query_window
            - window_adjustment
            - coverage
            - as_of
            - row_source
            - truncated
        applied_filters:
          type: object
          additionalProperties: {}
      required:
        - success
        - entity
        - data
        - meta
        - applied_filters
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.