# Get User Risk Score

`GET /api/radar/risk`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [2025-06-15/openapi.json](https://whitecircle.com/docs/2025-06-15/openapi.json)

Use this endpoint to retrieve a user's risk level using either `email` or `id`.

## How it works

White Circle can assess a user's Risk Score by correlating their recent sessions with policy violations. To enable this:

1. Send a [Check Session](https://whitecircle.com/docs/2025-06-15/endpoint/post.md) request and include the user's identifier in `metadata.user` (either `id` or `email`).
2. The Radar service aggregates the user's recent history and determines whether their behavior indicates elevated risk.
3. Query `GET /api/radar/risk` with the same `id` or `email` to fetch the current Risk Score.

> [!NOTE]
> Risk scoring is based on recent violations linked to the same user identifier. If we detect serious or repeated violations in the recent window, we return an elevated risk score.

## Adding user identity to Check Session

Include `metadata.user.id` or `metadata.user.email` in your Check Session payload. This lets Radar associate policy outcomes with a specific user over time.

```json
{
  "messages": [
    { "role": "user", "content": "Hello, can you check this for policy issues?" }
  ],
  "metadata": {
    "user": {
      "id": "user-123",
      "email": "user@example.com",
      "ip": "224.16.0.23",
      "mac_address": "00:11:22:33:44:55",
      "name": "John Doe"
    }
  }
}
```

> [!WARNING]
> At least one identifier is required: include `metadata.user.id` or `metadata.user.email`. For best results, include both.

> [!TIP]
> Provide richer context in `metadata.user` (for example, IP, email, or name) to improve correlation and the fidelity of the resulting risk analysis.

## Fetching the Risk Score

Use this endpoint to retrieve the current risk level for a user:

- `GET /api/radar/risk?email=user@example.com`
- `GET /api/radar/risk?id=user-123`

If recent violations exist for the user, Radar returns an elevated risk level; otherwise, it returns a normal risk level.

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2025-06-15"`.

## Query Parameters

- `email` (`string | null`, optional): User email address (provide either email or id, not both).
- `id` (`string | null`, optional): External user ID (provide either email or id, not both).

## Request example

```bash
curl --request GET \
  --url 'https://eu.whitecircle.com/api/radar/risk?email=user%40example.com' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2025-06-15'
```

## Response

### 200

Success

`application/json`

- `risk_level` (`enum<string>`, required): Available options: `normal`, `elevated`, `severe`.

**Example**

```json
{
  "risk_level": "normal"
}
```

### 400

Bad Request
