Alerts

List alerts

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

GET /v1/alerts

string

Opaque pagination cursor. Pass next_cursor from a previous response. Omit for the first page.

integer

default:"25"

Maximum items per page (1–100).

string

Filter by severity: low, medium, high, or critical.

string

Filter by status: open, acknowledged, or resolved.

Request

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

Response

{
  "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

string

Unique alert identifier (UUID).

string

Organization that owns this alert.

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)

string

Severity level: low, medium, high, or critical.

string

Current status: open, acknowledged, or resolved.

string

Short, human-readable alert title.

string

Detailed description of the alert.

string

UUID of the user who triggered the alert. null for system-level alerts.

string

UUID of the policy that was violated. null for non-policy alerts.

object

Additional context (model, provider, token counts, etc.). Schema varies by alert type.

string

ISO 8601 timestamp when the alert was created.

string

ISO 8601 timestamp when the alert was resolved. null if still open.

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`

To receive alerts in real time, configure a webhook or connect a SIEM integration.

Overview

Endpoints

List alerts

Request

Response

Alert object

Alert types reference

​List alerts

​Request

​Response

​Alert object

​Alert types reference

List alerts

Request

Response

Alert object

Alert types reference