Runs - Crewship

A “run” is one execution — either an ad-hoc agent/chat run (orchestrator picks up an assignment, exec’s the CLI) or a routine/pipeline run — and ends with one of COMPLETED / FAILED / CANCELLED / TIMEOUT. Since PR #234 the legacy agent_runs table is gone; runs are reconstructed from the Crew Journal. The two engines key their journal entries differently, and GET /api/v1/runs and GET /api/v1/runs/{id} read both (#2284):

An ad-hoc run’s entries (run.started + one terminal run.{completed|failed|cancelled|timeout}) are grouped on trace_id, which equals the run id.
A routine/pipeline run’s entries (pipeline.run.started + one terminal pipeline.run.{completed|failed}) never set trace_id; they’re grouped on actor_id instead, which the pipeline engine stamps to the run’s own id. There is no dedicated pipeline.run.cancelled — a run cancelled mid-flight is still pipeline.run.failed, with the real outcome on payload.status.

Every row carries kind: "agent" | "pipeline" so a caller can tell which engine produced it. The HTTP shape otherwise stays the one frontend consumers already know — this widened what rows can appear, not the shape of a row. GET /api/v1/runs/insights and the stats object embedded in GET /api/v1/runs are not widened by #2284 — both still aggregate ad-hoc runs only (journal.RunInsights / journal.RunStats). That was a deliberate scope limit: unifying cost roll-ups and correlation across the two engines is a separate decision with its own consequences. Every endpoint is workspace-scoped via the session context.

Runs are read-only — there is no write endpoint. An ad-hoc run comes into existence when the orchestrator emits run.started and concludes when a terminal run.{completed|failed|cancelled|timeout} lands on the same trace_id. A routine run comes into existence when the pipeline engine emits pipeline.run.started and concludes when pipeline.run.{completed|failed} lands on the same actor_id.

Endpoints

Method	Endpoint	Purpose
GET	`/api/v1/runs`	List runs with KPI tiles and pagination
GET	`/api/v1/runs/insights`	Fleet-ops aggregate (totals, latency, breakdowns) over a window
GET	`/api/v1/runs/{id}`	Get one run by trace id

List runs

GET /api/v1/runs

Returns a paginated list of runs with KPI tiles (stats) and pagination metadata. Backed by journal.ListRuns — a CTE-grouped read over journal_entries, keyed on trace_id for an ad-hoc run and actor_id for a routine/pipeline run (COALESCE(trace_id, actor_id), #2284) — plus journal.RunStats for the tiles (ad-hoc runs only; see the note above). Query parameters:

Param	Type	Description
`status`	string	Filter to one of `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, `TIMEOUT`. Invalid values → `400`. For a routine run, `FAILED`/`CANCELLED` are resolved from `payload.status` on its `pipeline.run.failed` terminal, since that entry type covers both outcomes.
`agent_id`	string	Filter by agent. For a routine run this is the invoking agent (empty for a schedule/webhook-triggered run with no invoking agent), not necessarily who executed each step.
`mission_id`	string	Only runs that worked on one issue — its mission id or its identifier (`ENG-4`), resolved per workspace.
`trigger`	string	Filter by `payload.trigger_type` on the `run.started` entry (e.g. `USER`, `WEBHOOK`, `CRON`). A routine run’s `trigger_type` in the list is derived from its `triggered_via` in the same vocabulary (`manual` → `USER`, `schedule`/`wake_check` → `CRON`, `webhook` → `WEBHOOK`), but the filter reads the journal payload, which routine runs do not populate — they are still excluded by this filter; use `kind` client-side to find them instead.
`tag`	string	Match a single tag inside `payload.metadata.tags` array on the `run.started` entry.

A kind: "pipeline" row also carries pipeline_slug, the routine it ran (empty for an agent run), and its trigger_type is derived from pipeline_runs.triggered_via in the same USER / CRON / WEBHOOK vocabulary as agent runs. | page | integer | 1-based page index, default 1. Values below 1 become 1; values above the server’s maximum page are capped. | | limit | integer | Page size, 1-100, default 50. Out-of-range values fall back to the default. | Response: 200 OK

{
  "data": [
    {
      "id": "run_a1b2c3",
      "workspace_id": "ws_123",
      "agent_id": "agt_viktor",
      "agent_name": "Viktor",
      "agent_slug": "viktor",
      "crew_name": "Backend",
      "crew_slug": "backend",
      "mission_id": "mis_42",
      "mission_identifier": "ENG-4",
      "chat_id": "chat_xyz",
      "triggered_by": "user_42",
      "trigger_type": "USER",
      "kind": "agent",
      "status": "COMPLETED",
      "started_at": "2026-04-30T10:00:00Z",
      "finished_at": "2026-04-30T10:02:00Z",
      "error_message": null,
      "exit_code": 0,
      "metadata": {"tags": ["urgent", "compliance"]},
      "model": "claude-opus-4-6",
      "created_at": "2026-04-30T10:00:00Z"
    },
    {
      "id": "run_p7q8r9",
      "workspace_id": "ws_123",
      "agent_id": "agt_viktor",
      "agent_name": "Viktor",
      "agent_slug": "viktor",
      "crew_name": "Backend",
      "chat_id": null,
      "triggered_by": null,
      "trigger_type": "CRON",
      "kind": "pipeline",
      "pipeline_slug": "nightly-digest",
      "status": "COMPLETED",
      "started_at": "2026-04-30T09:00:00Z",
      "finished_at": "2026-04-30T09:01:12Z",
      "error_message": null,
      "exit_code": null,
      "metadata": null,
      "created_at": "2026-04-30T09:00:00Z"
    }
  ],
  "stats": {
    "running": 1,
    "today": 12,
    "failed": 2
  },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 12,
    "total_pages": 1
  }
}

mission_id and mission_identifier name the issue the run worked on (from the run.started entry the dispatcher stamps); both are omitted for a chat-only run. crew_slug is what the crew’s page is keyed on. The same fields ride on GET /api/v1/runs/{id}.

Field	Type	Description
`data[].id`	string	The run’s `trace_id` (ad-hoc) or `actor_id` (routine/pipeline, #2284) — see `kind`.
`data[].kind`	string	`"agent"` for an ad-hoc agent/chat execution, `"pipeline"` for a routine run. Added in #2284.
`data[].status`	string	Computed from the terminal entry’s type. `RUNNING` when no terminal has landed. A routine run’s `pipeline.run.failed` terminal resolves to `CANCELLED` when `payload.status` says so, else `FAILED` — there is no dedicated `pipeline.run.cancelled` entry type.
`data[].started_at`	string?	RFC3339 from `run.started` / `pipeline.run.started`. Null only on a corrupt row that lost its starter.
`data[].finished_at`	string?	RFC3339 from the terminal entry. Null while still running.
`data[].error_message`	string?	Pulled from `terminal.payload.error_message`. Null on success.
`data[].exit_code`	integer?	Pulled from `terminal.payload.exit_code`. Ad-hoc runs only — a routine run’s terminal payload has no exit code, so this is always null for `kind: "pipeline"`.
`data[].metadata`	object?	Pulled from `started.payload.metadata`. Free-shape per orchestrator. Always null for a routine run — its `pipeline.run.started` payload doesn’t carry a `metadata` key.
`data[].model`	string?	The model the run actually resolved to (session-init ground truth). Omitted (`omitempty`) when unknown — older runs, non-Claude adapters, and every routine run (the pipeline engine doesn’t stamp this yet).
`data[].agent_name` / `agent_slug`	string?	Enriched from the `agents` table by the handler (one extra workspace-scoped SELECT per page).
`data[].crew_name`	string?	Enriched via the `agents.crew_id` → `crews.name` join.
`stats.running`	integer	Distinct trace_ids with `run.started` and no terminal in the workspace. Ad-hoc runs only — not widened by #2284.
`stats.today`	integer	Distinct trace_ids with `run.started` `ts >= start-of-today UTC`. Ad-hoc runs only.
`stats.failed`	integer	Distinct trace_ids with `run.failed` or `run.timeout` today. Ad-hoc runs only.

Errors:

Status	Condition
400	Invalid `status` value (must be one of the five enum values).
401	Not authenticated.
401	Authenticated request has no resolved workspace context.
403	Authenticated, but not a member of the resolved workspace.
500	DB error.

Fleet insights

GET /api/v1/runs/insights

Returns a fleet-operations aggregate over the workspace’s ad-hoc agent runs for a time window — every chat, CLI, webhook and cron invocation of an agent. Routine/pipeline runs are not included: the aggregate reads run.started traces only (journal.RunInsights, trace_id IS NOT NULL AND entry_type LIKE 'run.%'), and #2284 deliberately left it that way — see the note at the top of this page. The handler resolves per-agent counts into a crew rollup and a display-named top-agents leaderboard (one workspace-scoped agents→crews join). Query parameters:

Param	Type	Description
`window`	string	One of `24h`, `7d`, `30d`. Defaults to `24h` when omitted. Any other value → `400`.
`agent_id`	string	Only runs of this agent. Applied before aggregation and before the row cap.
`crew_id`	string	Only runs recorded under this crew. Uses the run’s recorded ownership, so moving an agent between crews does not move its history.

Response: 200 OK

{
  "window": "24h",
  "totals": { "total": 128, "succeeded": 119, "failed": 7, "running": 2 },
  "duration": { "p50_ms": 4200, "p95_ms": 31000 },
  "by_trigger": [ { "key": "USER", "total": 90, "failed": 3 } ],
  "by_model": [ { "key": "claude-opus-4-6", "total": 70, "failed": 2 } ],
  "by_crew": [ { "id": "crew_eng", "name": "Backend", "total": 60, "failed": 4 } ],
  "top_agents": [ { "id": "agt_viktor", "name": "Viktor", "crew_name": "Backend", "total": 42, "failed": 1 } ],
  "truncated": false
}

Field	Type	Description
`window`	string	The resolved window (`24h` / `7d` / `30d`).
`totals`	object	`total`, `succeeded`, `failed`, `running` run counts for the window.
`duration`	object	`p50_ms` / `p95_ms` run-duration percentiles.
`by_trigger`	array	Per-trigger breakdown: `{ key, total, failed }`. Always an array (never `null`).
`by_model`	array	Per-model breakdown: `{ key, total, failed }`.
`by_crew`	array	Per-crew rollup: `{ id, name, total, failed }`. Crewless agents bucket under `id: ""` / `name: "—"`. Capped at the top 8 by total.
`top_agents`	array	Leaderboard: `{ id, name, crew_name, total, failed }`. Capped at the top 8 by total.
`truncated`	bool	`true` when the underlying scan hit its row cap before covering the full window.

Status	Condition
`400`	`window` is not one of `24h` / `7d` / `30d`.
`401`	Not authenticated.
`401`	Authenticated request has no resolved workspace context.
`403`	Authenticated, but not a member of the resolved workspace.
`500`	Journal aggregate query failed.

Get a single run

GET /api/v1/runs/{id}

Returns a single run by id. The response shape is identical to one element of the data[] array from GET /api/v1/runs — the handler reuses the same enrichment so dashboard detail views can share the row renderer. Path parameters:

Param	Description
`id`	The run’s `trace_id` (ad-hoc) or `actor_id` (routine/pipeline). The caller doesn’t need to know which — `journal.GetRunByID` tries both (#2284).

Response: 200 OK

{
  "id": "run_a1b2c3",
  "workspace_id": "ws_123",
  "agent_id": "agt_viktor",
  "agent_name": "Viktor",
  "agent_slug": "viktor",
  "crew_name": "Backend",
  "chat_id": "chat_xyz",
  "triggered_by": "user_42",
  "trigger_type": "USER",
  "status": "COMPLETED",
  "started_at": "2026-04-30T10:00:00Z",
  "finished_at": "2026-04-30T10:02:00Z",
  "error_message": null,
  "exit_code": 0,
  "metadata": {"tags": ["urgent", "compliance"]},
  "model": "claude-opus-4-6",
  "created_at": "2026-04-30T10:00:00Z"
}

The handler uses the workspace-scoped indexed journal.GetRunByID lookup. A trace ID from another workspace is treated as not found.

Status	Condition
`400`	Empty `id` path segment.
`401`	Not authenticated.
`401`	Authenticated request has no resolved workspace context.
`403`	Authenticated, but not a member of the resolved workspace.
`404`	No run with that id in the caller’s workspace (cross-workspace probes are masked as 404 — the journal store filter never matches a foreign workspace’s trace id).
`500`	Journal page query failed, or enrichment returned an empty slice for a found row (data integrity issue).

Tenancy

workspace_id is taken from the session context — never from a query parameter.
Cross-tenant trace IDs are filtered out at the journal store (journal.ListRuns requires a non-empty WorkspaceID).
Enrichment lookup (agents + crews) is workspace-scoped, so an agent ID collision across workspaces (test fixtures, restored backups) cannot attach foreign names to a row.

Crew Journal guide — full event-type catalog and the run.* lifecycle.
Journal API — the underlying read surface, including FTS search and SSE live tail with trace_id filtering for one run’s spans.
crewship journal --trace-id <run-id> — list every span (LLM call, exec, network egress) belonging to one run.

​Endpoints

​List runs

​Fleet insights

​Get a single run

​Tenancy

​Related

Endpoints

List runs

Fleet insights

Get a single run

Tenancy

Related