POST /api/eval/smoke runs the built-in eval suite. The fleet summary (GET /api/fleet/summary) is on the Costs API page.
Observability is always on: there is no switch, and every route here answers. A trace is all events that share a traceId; the graph, metrics, error list and agent health are all worked out from the same rows. Every route is on the general rate tier (see rate limits).
Every response that carries event payloads masks credential-shaped keys and values in the event’s
data with •••• before sending it, on top of the secret scrub applied when the event was written. Numbers such as token counts and cost are kept. GET /api/obs/stream is a Server-Sent Events stream, documented below with its frames rather than a JSON body.Routes
GET /api/obs/events
Returns events from the log that match the query, ordered by seq, a number that only ever grows. The default order is asc (oldest first, the order things happened); pass order=desc for newest first.
- Path params: none.
- Query params:
- Request body: none.
Responses
200 OK: the matched events. Each row is the full stored shape with its data field redacted (still a JSON string after masking):
OrchestrationEventKind is one of 34 kinds: task_created, task_claimed, status_changed, comment_added, dep_linked, execution_started, execution_completed, tool_call, tool_result, cost, approval_requested, approval_resolved, pause_placed, pause_lifted, error, span_start, span_end, session_rotated, routine_fired, routine_dispatched, routine_completed, routine_error, routine_paused, team_chat_post, speaker_selected, turn_bound_hit, grant_decision, connector_health, task_wake_recorded, task_wake_skipped, task_wake_given_up, task_braked, job_limit_reached, job_limit_carried_on. See Events and errors for each kind’s data.
500 Internal Server Error: any read failure:
Example
GET /api/obs/traces/:traceId
Returns one trace: every event that shares the traceId, oldest first. A whole multi-agent task (the lead, the agents it delegated to, their tool calls) reads from this. The totals in metrics are worked out before each event’s data is masked, so cost and token figures are exact.
- Path params:
traceId(string). - Request body: none.
Responses
200 OK: the trace events plus the aggregate metrics:
traceId returns 200 with an empty events array and zeroed metrics.
500 Internal Server Error:
Example
GET /api/obs/errors
The error feed: error events, newest first, in a compact shape. Each error carries the class Clawboo sorted it into; an error it could not sort (class Unknown) is flagged harnessBug: true, a likely bug in Clawboo itself. Pass harnessBug=true to see only those.
- Path params: none.
- Query params:
- Request body: none.
error events by ts, then applies the harnessBug filter. Older errors are not reachable here; use GET /api/obs/events?kinds=error with afterSeq to page through them.
Responses
200 OK: the errors and the count of flagged ones. The whole response is masked before it is sent:
harnessBugCount ignores the harnessBug filter, so a client can show the count while listing every error.
500 Internal Server Error:
Example
GET /api/obs/health
Each agent’s current state, worked out from the event log against the current time. An agent with an open run is working while events keep arriving, stalled after 5 quiet minutes and zombie after 30 (its process has almost certainly died; the server’s stale-run cleanup closes such runs). An agent with no open run is idle.
- Path params: none.
- Query params:
teamId(string), scope to one team. - Request body: none.
Responses
200 OK: one entry per agent that appears in the window:
500 Internal Server Error:
Example
GET /api/obs/graph
Builds the task graph from the event log: tasks with their status and cost, the delegation and dependency edges between them, and the agent-to-agent delegations they imply. The same events always give the same graph.
- Path params: none.
- Query params:
teamId(string), scope to one team. - Request body: none.
Responses
200 OK: the graph. It carries no raw event data, so nothing in it is masked:
500 Internal Server Error:
Example
GET /api/obs/stream
A Server-Sent Events tail of the event log, optionally scoped to a team, task or agent and narrowed to a list of event kinds. The route polls the log every 750 ms past a seq cursor and sends any new events. It reads the database, so it also sees events that another process writes to the same database file. Resume with the EventSource Last-Event-ID header, ?afterSeq=<seq> or ?since=<seq>.
Where it starts. With no cursor, the cursor is 0: the stream first replays the whole log for its scope, 500 events per poll, and only then follows new events. This is the opposite of the chat streams, which start at the newest message. To watch only new events, pass the newest seq as afterSeq (read it with GET /api/obs/events?order=desc&limit=1).
- Path params: none.
- Query params:
The cursor is the first of
Last-Event-ID, afterSeq and since that holds a number of 0 or more. A missing, malformed or negative value is skipped, and with none left the cursor is 0. A browser’s EventSource reconnects to the same URL with the last id it received as Last-Event-ID, so that header wins over the query.
- Request body: none.
This is an SSE route: there is no JSON response body, and the catalog below describes the frames. Each poll reads up to 500 matching events past the cursor, oldest first. The cursor only moves forward, so resuming from an old cursor replays everything in scope after it.
Connection
On open, the handler writesHTTP/1.1 200 with:
: connected comment frame and flushes any rows already past the cursor.
Event catalog
An
activity event says the Inbox is worth reading again. seq is the board’s newest task change, recorded by database triggers, so it also moves for writes that leave no event row, such as an agent’s comment through its task tool. read goes up each time this person marks something read, so a read in one browser wakes the others. It never moves the resume cursor.
The data: payload is one stored event row, identical in shape to a GET /api/obs/events row, with its inner JSON data field masked (••••). The id: value is the row’s seq; the browser sends it back as Last-Event-ID on auto-reconnect, so the tail resumes without gaps.
Example frames:
Example
Following approvals
A client that shows or forwards approval cards, such as a notifier or a mirror, can follow them on this stream instead of pollingGET /api/tools/approvals:
- Read the newest
seqwithGET /api/obs/events?order=desc&limit=1(0when the log is empty). - Read the open cards with
GET /api/tools/approvals. - Open
GET /api/obs/stream?kinds=approval_requested,approval_resolved&afterSeq=<seq>, with no team, task or agent scope.
approvalId, the row’s id in the list. Each frame carries the agent, its team and the task (when known) on the row, and the approval id, kind and tool name in data. It never carries the call’s arguments, its reason or the command text. See Approval events for both shapes.
expiresAt. See approval_resolved for when an unanswered card’s event arrives.
POST /api/eval/smoke
Runs the smoke subset of Clawboo’s built-in eval suite (SMOKE_TASKS) and returns its report. It calls no model, needs no provider key, starts no runtime and uses no network. Each trial runs on its own throwaway board in a temporary SQLite file, never your clawboo.db, and the temporary files are removed afterwards. The ablation self-test runs only in the repository’s manual evals.yml workflow, never from this route.
- Path/query params: none.
- Request body:
Responses
200 OK: the suite report:
500 Internal Server Error: the run failed (the temporary files are still removed):
Example
Error envelope
Most error bodies are{ "error": "<message>" }; on the /api/obs/* routes the message is masked before it is sent. POST /api/eval/smoke answers the bare suite report rather than an object around it.
Related
- Observability: the event log, traces and agent health.
- Observability panel: the dashboard views over these routes.
- Events and errors: each event kind’s
dataand the error classes. - Costs API: cost records and the fleet summary.
- Board API: the board routes that write task events.