API Reference

Events

Events are the raw signals emitted by FORG adapters. Each event represents a single AI tool call: one model request with its response metadata. Events are immutable after ingestion.

The event object

{
  "id":          "evt_3a1b9c2d",
  "session_id":  "sess_4f9a2e1b8c3d",
  "user_id":     "user_abc123",
  "project_id":  "proj_xyz789",
  "ts":          "2025-05-28T09:14:37.422Z",
  "adapter":     "claude-code",
  "model":       "claude-opus-4-5",
  "tokens_in":   1024,
  "tokens_out":  512,
  "latency_ms":  1847,
  "cost_usd":    0.0042,
  "error_code":  null
}

Field reference

Field	Type	Description
`id`	string	Unique event identifier
`session_id`	string	Parent session
`user_id`	string	Developer who triggered the event
`project_id`	string \| null	Project context (from .forg.json or adapter)
`ts`	ISO 8601	Timestamp of the event (when the model call completed)
`adapter`	string	Which adapter emitted this event
`model`	string	Model identifier (e.g., `claude-opus-4-5`)
`tokens_in`	number	Input / prompt tokens consumed
`tokens_out`	number	Output / completion tokens generated
`latency_ms`	number	Time from request to first byte of response, in ms
`cost_usd`	number	Estimated cost in USD based on model pricing
`error_code`	string \| null	Non-null when the model call returned an error (e.g., `rate_limited`, `context_window_exceeded`)

List events

GET /api/v1/events

Parameter	Type	Description
`session_id`	string	Filter to a specific session
`user_id`	string	Filter by user
`project_id`	string	Filter by project
`model`	string	Filter by model (exact match)
`adapter`	string	Filter by adapter name
`from`	ISO 8601	Events at or after this time
`to`	ISO 8601	Events before this time
`error_only`	boolean	If true, only return events with non-null error_code
`limit`	number	Page size (default: 20, max: 100)
`cursor`	string	Pagination cursor

curl "https://forg.pro/api/v1/events?session_id=sess_4f9a2e1b8c3d" \
  -H "Authorization: Bearer forg_live_..."

{
  "data": [
    {
      "id": "evt_3a1b9c2d",
      "model": "claude-opus-4-5",
      "tokens_in": 1024,
      "tokens_out": 512,
      "cost_usd": 0.0042,
      "ts": "2025-05-28T09:14:37.422Z"
    },
    ...
  ],
  "cursor": "evt_5d2e8f3a",
  "has_more": true
}

Get a single event

GET /api/v1/events/:id