--- title: "Risk Events Search" method: POST path: "/risk-events-search" tags: ["Risk Events"] --- # Risk Events Search `POST /risk-events-search` ## Request - Base URL: `https://api.signal-ai.com` - URL: `https://api.signal-ai.com/risk-events-search` - Auth: OAuth 2 - Client credentials - Token URL: `https://api.signal-ai.com/auth/token` scopes: `risk-events` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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.dev/signal-ai/apis/signal-ai-api.md) - [All operations](https://skmtc.dev/signal-ai/apis/signal-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signal-ai/apis/signal-ai-api/revisions/0ab7ff186291?raw)