> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitecircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get User Risk Score

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](/2025-06-15/endpoint/post) 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.

<Info>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.</Info>

## 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 theme={null}
{
  "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 <code>metadata.user.id</code> or <code>metadata.user.email</code>. For best results, include both.</Warning>

<Tip>Provide richer context in <code>metadata.user</code> (for example, IP, email, or name) to improve correlation and the fidelity of the resulting risk analysis.</Tip>

## 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.


## OpenAPI

````yaml GET /api/radar/risk
openapi: 3.1.0
info:
  title: WhiteCircle API Backend
  version: '2025-06-15'
servers:
  - url: https://eu.whitecircle.com
  - url: https://us.whitecircle.com
security: []
tags:
  - name: Protect
    description: Content protection and policy checking
  - name: Radar
    description: Risk assessment and user scoring
paths:
  /api/radar/risk:
    get:
      tags:
        - Radar
      operationId: risk
      parameters:
        - name: whitecircle-version
          in: header
          description: API Version
          required: true
          schema:
            type: string
          example: '2025-06-15'
        - name: email
          in: query
          description: User email address (provide either email or id, not both)
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: id
          in: query
          description: External user ID (provide either email or id, not both)
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRiskResponse'
        '400':
          description: Bad Request
      security:
        - bearerAuth: []
components:
  schemas:
    UserRiskResponse:
      type: object
      required:
        - risk_level
      properties:
        risk_level:
          $ref: '#/components/schemas/RiskLevel'
      example:
        risk_level: normal
    RiskLevel:
      type: string
      enum:
        - normal
        - elevated
        - severe
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key required. Format: Bearer wc-your-api-key'

````