Skip to main content
These routes read the server’s event log, the durable record of what happened on the board and in runs: tasks created and claimed, status changes, runs, tool calls, costs, approvals and errors. They return the raw feed, one trace with its totals, the error feed, each agent’s health, the task-delegation graph, and a live stream. They only read: every event is written by the server itself, and no route adds events from outside. 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:
The trace read is capped at 5000 events. An unknown 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.
The route always reads the 500 newest 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.
Only the most recent 5000 events in scope are read. The event log only grows (nothing prunes it), so this works from a recent window, not the whole history: an agent whose activity has scrolled out of the window stops appearing.

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.
Only the most recent 5000 events in scope are read, as for health. A task whose events have all left that window stops appearing, and a task partly inside it is drawn from the events that remain.

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 writes HTTP/1.1 200 with:
then emits a : 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 polling GET /api/tools/approvals:
  1. Read the newest seq with GET /api/obs/events?order=desc&limit=1 (0 when the log is empty).
  2. Read the open cards with GET /api/tools/approvals.
  3. Open GET /api/obs/stream?kinds=approval_requested,approval_resolved&afterSeq=<seq>, with no team, task or agent scope.
A card opened between steps 1 and 2 arrives in both the list and the stream, so match cards by 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.
A card stops being answerable at its 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:
Both values are rounded down and kept between 1 and 3, so the run stays small.

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.
Last modified on November 7, 2026