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

# Risk Events Search

`POST /risk-events-search`

With our risk events search you can find significant events that impact business risk, extracted from our dataset of global news.

Events are derived from news content and clustered on a daily basis. Each event instance is labelled according to the [Risk Event Definition][] it matched. It also includes information about the entities that instigated the event ("actors"), and those directly impacted ("targets").

### Search query criteria

Construct a query to find events of interest by specifying matching criteria. The matching criteria are expressed in a `where` clause of the request body (see below). This works in a similar way to [Content Search][], however there is a more limited set of criteria and `exclude` clauses are not supported.

The criteria available are:

- the entities that were involved in the event, either as actors or targets
- the event definitions
- a date range of when the event was first reported

The returned data will be paginated, with a maximum of 100 results per page depending on the requested `size` paramater. For more information see the [Pagination][] docs.

### Risk event metadata returned

- unique event ID
- the definition the event matched
- the date the event was first reported
- the date we first detected the event (normally the same as first reported)
- the entities who were the "actors" in the event i.e. those that instigated or caused the event
- the entities who were the "targets" of the event i.e. those who were directly impacted by the event
- a list of documents that mentioned the event - id, headline and link will be provided, additional metadata can be retrieved using the [Get Document][] endpoint

[Risk Event Definition]: #tag/Risk-Events/operation/risk-events-definitions
[Get Document]: #tag/Content-Search/operation/get-document
[Content Search]: #tag/Content-Search
[Pagination]: #section/Pagination

## Request body

- RiskEventSearchQuery
  - `where` RiskEventMatch, required
    - `first-reported-at` DateRangeMatch
      - `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.
      - `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.
    - `entities` RiskEventEntitiesMatch
      - `id` object, required
        - `any` ResourceId[], required
    - `event-definitions` RiskEventDefinitionsMatch
      - `id` object, required
        - `any` ResourceId[], required
  - `size` number — Set the number of events to return per page
  - `from-cursor` string — Use the `next-cursor` field from a previous response to get the next page of results (see [Pagination](#section/Pagination))

## Response `200`

Returns a list of events matching the query

- RiskEventSearchResponse
  - `events` RiskEvent[], required
    - `id` string, uuid, required
    - `title` string, required — A short description of the event
    - `event-definition` RiskEventDefinition, required
      - `id` string, required
      - `name` string, required
      - `description` string
    - `first-reported` 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.
    - `first-detected` 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.
    - `actors` Entity[], required — The entities that instigated the event
      - `id` string, uuid, required
      - `type` 'person' | 'organisation' | 'location' | 'substance' | 'disease' | 'product' | 'regulation', required
      - `name` string, required
    - `targets` Entity[], required — The entities that were impacted by the event
      - `id` string, uuid, required
      - `type` 'person' | 'organisation' | 'location' | 'substance' | 'disease' | 'product' | 'regulation', required
      - `name` string, required
    - `documents` RiskEventDocument[], required — The IDs and headlines from up to 3 articles mentioning the event. Further details can be obtained from the Document API
      - `id` string, uuid, required
      - `title` string, required
      - `signal-url` string
  - `next-cursor` string — Use the `next-cursor` field from a previous response to get the next page of results (see [Pagination](#section/Pagination))

---

[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/revisions/0ab7ff186291/schema)