reference
Runner Events
Telemetry protocol — how agents report checkpoints to the API server.
Agents send telemetry to POST /internal/v1/runners/events (local) or POST /v1/runners/events (cloud). Auth: Authorization: Bearer <token>.
Event types
| Type | When | Description |
|---|---|---|
thread_started | Start of a run | Creates the initial checkpoint row |
checkpoint | After each turn | Full state snapshot with history and cost fields |
thread_completed | Run finished | Updates status to completed |
thread_error | Run failed | Updates status to error with error info |
thread_budget_exceeded | Budget exhausted | Updates status to budget_exceeded and merges cost into metadata |
budget_warning | 80% budget consumed | Informational — logged; cost data already in checkpoint metadata |
Payload format
JSON
{
"events": [
{
"type": "thread_started",
"data": {
"thread_id": "my-project",
"trace_id": "abc123",
"agent_id": "researcher",
"model": "claude-sonnet-4-6"
}
},
{
"type": "checkpoint",
"data": {
"thread_id": "my-project",
"trace_id": "abc123",
"parent_trace_id": null,
"agent_id": "researcher",
"step_index": 3,
"status": "in_progress",
"history": [...],
"history_meta": [...],
"tokens_used": 420,
"input_tokens": 310,
"output_tokens": 110,
"model": "claude-sonnet-4-6",
"turn_start_history_len": 4,
"pending_tool_calls": [],
"run_cost_usd": 0.002310,
"budget_usd": 0.5,
"budget_warning": false
}
},
{
"type": "thread_completed",
"data": {
"thread_id": "my-project",
"tokens_used": 420,
"model": "claude-sonnet-4-6"
}
}
]
}history_meta
history_meta is a parallel list to history. Each entry contains timing and token data:
JSON
// For assistant messages:
{"ts": "2025-03-14T09:00:01.123Z", "tokens_in": 310, "tokens_out": 110}
// For all other messages:
{"ts": "2025-03-14T09:00:00.000Z"}