Runs API

Query and inspect agent runs, including their steps, tool calls, risk events, and approvals.

List runs

GET /v1/runs

Auth: JWT Bearer Token

Query parameters

Parameter	Type	Description
status	string	Filter by run status (running, completed, failed)
agent	string	Filter by agent ID
risk	string	Filter by highest risk level (low, medium, high, critical)
from	ISO date	Start of date range
to	ISO date	End of date range
limit	number	Max results (default: 50)
offset	number	Pagination offset

Example

# All runs
curl http://localhost:3000/v1/runs \
  -H "Authorization: Bearer $TOKEN"

# Filter by status and risk
curl "http://localhost:3000/v1/runs?status=completed&risk=high&limit=10" \
  -H "Authorization: Bearer $TOKEN"

# Filter by agent and date range
curl "http://localhost:3000/v1/runs?agent=claude-code-maria&from=2026-03-01" \
  -H "Authorization: Bearer $TOKEN"

Response

[
  {
    "runId": "run_abc123",
    "agentId": "claude-code-maria",
    "status": "completed",
    "startedAt": "2026-03-19T10:00:00.000Z",
    "completedAt": "2026-03-19T10:05:32.000Z",
    "durationMs": 332000,
    "highestRiskLevel": "high",
    "reason": "Fix authentication bug in session handler",
    "agentContext": {
      "goal": "Fix the session expiry bug",
      "reasoning": "Sessions expire prematurely after re-login",
      "conversationId": "conv_abc123"
    },
    "toolCallCount": 12,
    "blockedCount": 1,
    "approvalCount": 2
  }
]

---

Get run details

GET /v1/runs/:id

Auth: JWT Bearer Token

Returns full run details including:

• Steps with their tool calls
• All tool calls with input/output payloads
• Risk events
• Approval requests
• Audit log entries

Example

curl http://localhost:3000/v1/runs/run_abc123 \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "runId": "run_abc123",
  "agentId": "claude-code-maria",
  "status": "completed",
  "startedAt": "2026-03-19T10:00:00.000Z",
  "completedAt": "2026-03-19T10:05:32.000Z",
  "reason": "Fix auth module session expiry bug",
  "agentContext": {
    "goal": "Fix the session expiry bug",
    "reasoning": "Sessions expire prematurely after re-login"
  },
  "metadata": { "task": "Fix auth module" },
  "steps": [
    {
      "stepId": "step_001",
      "status": "completed",
      "metadata": { "phase": "analysis" }
    }
  ],
  "toolCalls": [
    {
      "toolCallId": "tc_001",
      "toolName": "read_file",
      "status": "completed",
      "inputPayload": { "path": "src/auth.ts" },
      "outputPayload": { "lines": 142 },
      "initiatedAt": "2026-03-19T10:00:05.000Z",
      "completedAt": "2026-03-19T10:00:05.500Z"
    },
    {
      "toolCallId": "tc_002",
      "toolName": "deploy",
      "status": "blocked",
      "inputPayload": { "environment": "production" },
      "reason": "Deploying the fix to resolve customer-facing bug",
      "agentContext": {
        "goal": "Fix the session expiry bug",
        "reasoning": "Fix verified in staging, deploying to production"
      },
      "blockedReason": "Matched policy: block-destructive-ops",
      "initiatedAt": "2026-03-19T10:03:00.000Z"
    }
  ],
  "riskEvents": [
    {
      "severity": "critical",
      "policyId": "pol_001",
      "toolCallId": "tc_002",
      "action": "block"
    }
  ],
  "approvals": [],
  "auditLogs": [
    {
      "auditId": "aud_001",
      "action": "run.started",
      "actorType": "agent",
      "actorId": "agent:claude-code-maria",
      "timestamp": "2026-03-19T10:00:00.000Z"
    }
  ]
}