Skip to main content

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.

​
List alerts

Returns a cursor-paginated list of alerts for your organization. 
GET /v1/alerts
​
cursor
string
Opaque pagination cursor. Pass next_cursor from a previous response. Omit for the first page.
​
limit
integer
default:"25"
Maximum items per page (1–100).
​
severity
string
Filter by severity: low, medium, high, or critical.
​
status
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

​
id
string
Unique alert identifier (UUID).
​
org_id
string
Organization that owns this alert.
​
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)
​
severity
string
Severity level: low, medium, high, or critical.
​
status
string
Current status: open, acknowledged, or resolved.
​
title
string
Short, human-readable alert title.
​
message
string
Detailed description of the alert.
​
user_id
string
UUID of the user who triggered the alert. null for system-level alerts.
​
policy_id
string
UUID of the policy that was violated. null for non-policy alerts.
​
metadata
object
Additional context (model, provider, token counts, etc.). Schema varies by alert type.
​
created_at
string
ISO 8601 timestamp when the alert was created.
​
resolved_at
string
ISO 8601 timestamp when the alert was resolved. null if still open.

​
Alert types reference

TypeTriggered byTypical severity
policy_violationA policy action: alert or action: block firesmedium – critical
budget_exceededSpend reaches the budget limithigh
anomaly_detectedPre-departure anomaly or unusual usage spikehigh – critical
security_eventEmployee lockout triggered, device cert revokedcritical
To receive alerts in real time, configure a webhook or connect a SIEM integration.