API Reference

Ingest billable events from your AI agents. Simple REST API, sub-millisecond latency.

Base URL

Ingest Events

POST/api/events

Record a single billable event from an agent.

Field	Type	Description
agent_idrequired	string	Unique identifier for the agent
event_typerequired	string	Type of billable event (e.g. "api_call", "token_usage")
units	number	Number of billable units (default: 1)
metadata	object	Arbitrary JSON metadata

curl -X POST /api/events \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_9x4k2m",
    "event_type": "api_call",
    "units": 142,
    "metadata": { "model": "gpt-4o", "latency_ms": 89 }
  }'

POST/api/events/batch

Ingest up to 1000 events in a single request.

curl -X POST /api/events/batch \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "agent_id": "agent_01", "event_type": "api_call", "units": 50 },
      { "agent_id": "agent_02", "event_type": "token_usage", "units": 1200 }
    ]
  }'

Query Events

GET/api/events/summary

Get high-level totals across all agents. Supports since and until query params (ISO timestamps).

GET/api/events/stats

Get per-agent breakdown: event count, total units, event types, first/last event times.

GET/api/events/hourly

Get hourly aggregates for the last 24 hours. Optional agent_id filter.

GET/api/events

List recent events with pagination. Supports limit, offset, and agent_id query params.