Skip to content

Read a run

Open as Markdown

You can read a run three ways: in the app, over HTTP, or through the MCP tools. We will take the same document through each useful view, then page through the heavier spans and logs separately. All three entry points assemble the run at read time from every source. Concepts explains its fields; Contracts lists every one.

Signed in to the app, open a run from the list, or go to /runs/superpipeline/{board}/{run}. The run view shows the run’s title, status and a strip of facts (agent, attempts, errors, duration and cost), and tabs for the trace, logs, errors, verdicts and attempts. A source that did not answer shows as unavailable in its tab, and a value no source supplied reads unknown, never 0.

Terminal window
curl -H 'Authorization: Bearer <token>' \
https://superwitness.example.internal/v1/runs/superpipeline/brd_01/run_01

GET /v1/runs/superpipeline/{board}/{run} returns the run document. Board and run ids are letters, digits, _ and -, starting with a letter or digit, up to 128 characters; anything else is 400 invalid_run_ref. The answer is 404 run_not_found only when SuperPipeline and the AgentPod hub both answer that they do not know the run. Any other failure of a source is a 200 with that source’s status in sources.

The response gives you the joined view even when one source is having a bad day. Read sources first and you know whether a 0 is a real 0, an unknown is missing evidence, or a dependency needs attention.

The document’s links hold the paths for this run:

"links": {
"self": "/v1/runs/superpipeline/brd_01/run_01",
"spans": "/v1/runs/superpipeline/brd_01/run_01/spans",
"logs": "/v1/runs/superpipeline/brd_01/run_01/logs"
}

GET /v1/runs/by-attempt/{attempt} asks the AgentPod hub which run an attempt belongs to and answers 302, with the run document’s path in Location:

HTTP/1.1 302 Found
Location: /v1/runs/superpipeline/brd_01/run_01

An attempt id is attempt_<id>; anything else is 400 invalid_attempt_id. The hub not knowing the attempt is 404 attempt_not_found, and an attempt that was not dispatched from a SuperPipeline run is 404 attempt_has_no_run.

The redirect gives you the canonical run address, so an attempt link becomes a run link without a second lookup in your client.

GET /v1/runs/superpipeline/{board}/{run}/spans?cursor=&limit= lists the run’s spans, oldest first (by start time, then trace id, then span id):

{
"spans": [
{
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"name": "dispatch",
"service": "agentpod-hub",
"start": "2026-10-04T10:00:00Z",
"duration_ms": 300000,
"attributes": {"board.id": "brd_01", "card.id": "crd_01", "external.source": "superpipeline", "run.id": "run_01"}
}
],
"next_cursor": "eyJvIjoxfQ"
}

Each span has trace_id, span_id, parent_span_id (left out for a span with no parent), name, service, start, duration_ms and attributes, whose values are all strings. next_cursor is left out on the last page. Which spans count as the run’s is covered in Sending telemetry.

GET /v1/runs/superpipeline/{board}/{run}/logs?cursor=&level=&limit= lists the run’s log lines, oldest first:

{
"logs": [
{
"at": "2026-10-04T10:00:02Z",
"service": "agentpod-hub",
"level": "info",
"message": "attempt opened",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b8",
"run_id": "run_01"
}
],
"next_cursor": "eyJvIjoxfQ",
"trace_join": "ok"
}
  • level filters by level: debug, info, warn or error. Left out, every level is listed. Any other value is 400 invalid_level.
  • Each line’s level is one of debug, info, warn, error or unknown, and service is unknown when the line has no service name. trace_id, span_id and run_id are left out when the line has none.
  • next_cursor is null on the last page.
  • A line belongs to the run when it carries the run’s id, or one of the run’s trace ids. To know the trace ids, SuperWitness first reads the run’s spans; trace_join is the traces source’s status for that read. When it is not ok, lines were matched by run id alone.

Both lists page the same way:

  • limit is the page size. Left out, it is 100; above 500, it is 500. Anything that is not a whole number of at least 1 is 400 invalid_limit.
  • cursor is the next_cursor from the previous page. Treat it as opaque. A cursor SuperWitness did not issue is 400 invalid_cursor.

If the engine behind a list cannot answer, the request fails rather than returning an empty page: traces_unavailable or logs_unavailable (503), traces_timeout or logs_timeout (504), or traces_unauthorized or logs_unauthorized (502). The HTTP API lists every error. Follow next_cursor until it is absent or null and you have the ordered evidence; if a source fails, you get an explicit failure instead of an empty page wearing a convincing hat.