---
title: "Events Search"
method: POST
path: "/events"
tags: ["Events"]
---

# Events Search

`POST /events`

## Request body

- EventSearchQuery
  - `where` EventMatch, required
    - `date` object
      - `gt` string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
      - `gte` string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
      - `lt` string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
      - `lte` string, date — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
    - `topics` EventTopicsMatch
      - `id` union, required
        - object
          - `any` ResourceId[], required
          - `all` unknown
        - object
          - `all` ResourceId[], required
          - `any` unknown
    - `entities` EventEntitiesMatch
      - `id` union, required
        - object
          - `any` ResourceId[], required
          - `all` unknown[]
            - unknown
        - object
          - `all` ResourceId[], required
          - `any` unknown[]
            - unknown
    - `labels` union — Filter on specific words or phrases. A label can contain a maximum of 6 words.
      - object
        - `any` string[]
      - object
        - `all` string[]
    - `sources` object — If the user does not have access to any of the sources specified, those ids will be excluded while fetching the events
      - `id` union, required
        - object
          - `any` ResourceId[], required
          - `all` unknown
        - object
          - `all` ResourceId[], required
          - `any` unknown
  - `exclude` EventExclude
    - `entities` object
      - `id` object, required
        - `any` ResourceId[], required
    - `topics` object
      - `id` object, required
        - `any` ResourceId[], required
    - `labels` object
      - `any` string[]
    - `sources` object
      - `id` object, required
        - `any` ResourceId[], required
  - `size` integer
  - `from-cursor` string

## Response `200`

Returns a list of events matching the query

- EventSearchResponse
  - `events` Event[], required
    - `labels` string[], required — The most descriptive words or phrases that appear in the documents in the event.
    - `date` string, date, required — A date based on the IETF RFC 3339 format (e.g. `2023-01-01`). Note that a day is the span of time between 00:00:00 and 23:59:59 based on the UTC timezone. You may prefer using the `date-time` option to match days in a different timezone.
    - `document-count-entitlements` integer, required — The number of documents that mentioned this event based on your user permissions.
    - `hash` string, required
    - `story-count-global` integer, required — The number of stories that mentioned this event across Signal's global data set.
    - `story-ids` ResourceId[], required — Ordered by centrality - how well the story represents the event in question. You can use these ids in the [Search API](#tag/Content-Search/operation/search-documents) to get headlines best describing the event.
    - `document-count-global` integer, required — The number of documents that mentioned this event across Signal's global data set.
    - `entities` EventEntity[], required
      - `id` string, uuid, required
      - `type` 'person' | 'organisation' | 'location' | 'substance' | 'disease' | 'product' | 'regulation', required
      - `name` string, required
      - `story-count` integer
      - `prominence-score` number — The number of stories mentioning the concept divided by the story count for the event. For example, if half the stories in the event mention an entity then the prominence would be 0.5.
    - `topics` EventTopic[], required
      - `id` string, uuid, required
      - `name` string, required
      - `story-count` integer
      - `prominence-score` number — The number of stories mentioning the concept divided by the story count for the event. For example, if half the stories in the event mention a topic then the prominence would be 0.5.
    - `source-count-global` integer, nullable — The number of sources that mentioned this event across Signal's global data set.
  - `event-hash-expiry` string, date-time, required — When the event hashes will expire (note that it could still be available after this time).
  - `next-cursor` string
  - `stats` object, required — The number of events matched across our entire data set. We can only provide an accurate figure up to 10000. Anything above that is indicated with `gte`.
    - `total` unknown[], required
      - unknown

---

[API](https://skmtc.net/signal-ai/apis/signal-ai-api.md) · [All operations](https://skmtc.net/signal-ai/apis/signal-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/signal-ai/signal-ai-api/versions/867c43388206/schema)