---
title: "Risk Events Scores"
method: POST
path: "/risk-events-scores"
tags: ["Risk Events"]
---

# Risk Events Scores

`POST /risk-events-scores`

Our risk scoring methodology provides an indication of how exposed a company may be to a specific risk. It does this by looking at the frequency of particular types of events, and how prominent this type of event is in the news media.

### Scoring query criteria

Scoring is based on selecting events for a date range and a "cohort" of entities with a `where` clause, then applying scoring options with a `score-by` clause.

The `where` clause is a subset of what is available in [Risk Events Search][]. It requires entities and a date range. The entities that make up this cohort represent a benchmark for scoring against.

The `score-by` clause has two optional properties:

- the entities to score, which should be a subset of the entities that made up the cohort defined in the `where`
- the risk "pillars" which group different event definitions into arbitrary buckets

The default behaviour without either of these options is to return a score for every available [Risk Event Definition][]. This tells you the overall risk score for the cohort.

With the entities option set, a score is returned for every combination of Event Definition and the entities provided. This tells you the risk score for each entity.

With the pillars option set, rather than getting a score for each event definition you will get a score for that group of event definitions. This allows organising the event definitions into arbitrary buckets to support different kinds of risk framework. When combined with the entities option a score is returned for each combination of entity and pillar.

### Score data returned

The score data will include:

- a name for each data point, which is either the pillar name provided, or the event definition name if pillars were not used
- a list of the relevant event definitions, either from the pillar, or a list of one event definition if pillars were not used
- optionally an entity, if entities were provided
- the count of documents
- the count of event instances
- a number from 1 to 5 which represents the "likelihood" of the event based on previous frequency
- a number from 1 to 5 which represents the "impact" of the event based on media prominence both absolutely and relatively to the cohort
- the score, which is likelihood multiplied by impact, so always a number from 1 to 25

[Risk Events Search]: #tag/Risk-Events/operation/risk-events-search
[Risk Event Definition]: #tag/Risk-Events/operation/risk-events-definitions

## Request body

- RiskEventScoreQuery
  - `where` RiskScoreMatch, required
    - `first-reported-at` DateRangeMatch, required
      - `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, required
      - `id` object, required
        - `any` ResourceId[], required
  - `score-by` RiskScoreBy, required
    - `entity-ids` ResourceId[]
    - `pillars` RiskPillar[]
      - `name` string, required
      - `event-definition-ids` ResourceId[], required

## Response `200`

Returns a list of events matching the query

- RiskEventScoreResponse
  - `scores` RiskScore[], required
    - `name` string, required
    - `event-definitions` RiskEventDefinition[], required
      - `id` string, required
      - `name` string, required
      - `description` string
    - `entity` Entity
      - `id` string, uuid, required
      - `type` 'person' | 'organisation' | 'location' | 'substance' | 'disease' | 'product' | 'regulation', required
      - `name` string, required
    - `document-count` number, required
    - `event-count` number, required
    - `likelihood` number, required
    - `impact` number, required
    - `score` number, required

---

[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/867c43388206/schema)