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

# Alerts

> List alerts generated by policy violations and system events.

## List alerts

Returns a cursor-paginated list of alerts for your organization.

```bash theme={null}
GET /v1/alerts
```

<ParamField query="cursor" type="string">
  Opaque pagination cursor. Pass `next_cursor` from a previous response. Omit for the first page.
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Maximum items per page (1–100).
</ParamField>

<ParamField query="severity" type="string">
  Filter by severity: `low`, `medium`, `high`, or `critical`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `open`, `acknowledged`, or `resolved`.
</ParamField>

### Request

```bash theme={null}
curl "https://api.toktra.io/v1/alerts?severity=high&status=open" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response

```json theme={null}
{
  "items": [
    {
      "id": "al1b2c3d-0000-0000-0000-000000000001",
      "org_id": "a1b2c3d4-0000-0000-0000-000000000000",
      "type": "policy_violation",
      "severity": "high",
      "status": "open",
      "title": "GPT-4 usage by non-engineering user",
      "message": "User jane.smith@acme.com used gpt-4 (model restricted to Engineering department).",
      "user_id": "u1a2b3c4-0000-0000-0000-000000000001",
      "policy_id": "p1a2b3c4-0000-0000-0000-000000000001",
      "metadata": {
        "model": "gpt-4",
        "provider": "openai",
        "token_count": 4200
      },
      "created_at": "2025-01-15T10:30:00Z",
      "resolved_at": null
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total_count": 1
}
```

***

## Alert object

<ResponseField name="id" type="string">
  Unique alert identifier (UUID).
</ResponseField>

<ResponseField name="org_id" type="string">
  Organization that owns this alert.
</ResponseField>

<ResponseField name="type" type="string">
  Alert type:

  * `policy_violation` — a policy was triggered
  * `budget_exceeded` — a budget limit was reached
  * `anomaly_detected` — unusual usage pattern detected
  * `security_event` — security-related event (e.g., pre-departure anomaly)
</ResponseField>

<ResponseField name="severity" type="string">
  Severity level: `low`, `medium`, `high`, or `critical`.
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `open`, `acknowledged`, or `resolved`.
</ResponseField>

<ResponseField name="title" type="string">
  Short, human-readable alert title.
</ResponseField>

<ResponseField name="message" type="string">
  Detailed description of the alert.
</ResponseField>

<ResponseField name="user_id" type="string">
  UUID of the user who triggered the alert. `null` for system-level alerts.
</ResponseField>

<ResponseField name="policy_id" type="string">
  UUID of the policy that was violated. `null` for non-policy alerts.
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional context (model, provider, token counts, etc.). Schema varies by alert type.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the alert was created.
</ResponseField>

<ResponseField name="resolved_at" type="string">
  ISO 8601 timestamp when the alert was resolved. `null` if still open.
</ResponseField>

***

## Alert types reference

| Type               | Triggered by                                      | Typical severity      |
| ------------------ | ------------------------------------------------- | --------------------- |
| `policy_violation` | A policy `action: alert` or `action: block` fires | `medium` – `critical` |
| `budget_exceeded`  | Spend reaches the budget limit                    | `high`                |
| `anomaly_detected` | Pre-departure anomaly or unusual usage spike      | `high` – `critical`   |
| `security_event`   | Employee lockout triggered, device cert revoked   | `critical`            |

<Tip>
  To receive alerts in real time, configure a [webhook](/api/webhooks) or connect a [SIEM integration](/integrations/siem).
</Tip>