Monitor & Analyze

Poll status, get full audit trails, and register webhooks

Every agent run produces a complete audit trail — the final output, every tool call, token usage, and execution logs. Two ways to get notified when a run completes: polling and webhooks.

Polling status

Endpoint

GET /agent/v1/run/:id/status

Lightweight endpoint — returns only the status and timing, no output or steps.

cURL

curl "https://api.case.dev/agent/v1/run/$RUN_ID/status" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Response

{
  "id": "run_abc123",
  "status": "completed",
  "startedAt": "2025-01-15T10:30:05Z",
  "completedAt": "2025-01-15T10:35:22Z",
  "durationMs": 317000
}

Field	Description
status	queued, running, completed, failed, or cancelled
durationMs	Elapsed time. For running tasks, this updates on each poll.

Poll every 2-5 seconds. Status is a lightweight read — no rate limit concerns at this interval.

---

Getting full results

Endpoint

GET /agent/v1/run/:id/details

Returns everything: the output, every step the agent took, token usage, and execution logs.

cURL

curl "https://api.case.dev/agent/v1/run/$RUN_ID/details" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Response

{
  "id": "run_abc123",
  "agentId": "agent_xyz",
  "status": "completed",
  "prompt": "Research employment law...",
  "result": {
    "output": "## Research Report\n\nBased on my analysis of the vault documents...",
    "logs": {
      "server": "agent server listening on http://0.0.0.0:4096...",
      "runner": "[runner] Sending prompt to agent..."
    }
  },
  "usage": {
    "model": "anthropic/claude-sonnet-4.6",
    "inputTokens": 45000,
    "outputTokens": 3200,
    "toolCalls": 12,
    "durationMs": 317000
  },
  "steps": [
    {
      "id": "step_001",
      "type": "tool_call",
      "toolName": "bash",
      "toolInput": { "command": "casedev vault list" },
      "toolOutput": "{ \"vaults\": [...] }",
      "durationMs": 1200,
      "timestamp": "2025-01-15T10:30:10Z"
    },
    {
      "id": "step_002",
      "type": "output",
      "content": "I found 3 vaults. Let me search the most relevant one...",
      "timestamp": "2025-01-15T10:30:12Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "startedAt": "2025-01-15T10:30:05Z",
  "completedAt": "2025-01-15T10:35:22Z"
}

Response fields

Field	Type	Description
result.output	string	The agent’s final text response
result.logs	object	Sandbox execution logs (agent server + runner script)
usage.inputTokens	number	Total input tokens consumed
usage.outputTokens	number	Total output tokens generated
usage.toolCalls	number	Number of tool invocations
steps	array	Ordered list of every action the agent took

Step types

Type	Description
output	Text generated by the agent
thinking	Internal reasoning (if model supports it)
tool_call	Tool invocation with input
tool_result	Tool output/response

---

Watching runs

Register an HTTPS callback URL to get notified when a run completes. Useful for production workflows where you don’t want to poll.

Endpoint

POST /agent/v1/run/:id/watch

cURL

# Register watcher
curl -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/watch" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callbackUrl": "https://your-app.com/webhooks/agent-run"}'

# Then execute
curl -X POST "https://api.case.dev/agent/v1/run/$RUN_ID/exec" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Callback requirements

Requirement	Details
Protocol	HTTPS only — HTTP is rejected
Network	Must be publicly reachable — private IPs, localhost, and .local domains are blocked
Multiple watchers	You can register multiple callback URLs for the same run
Retries	3 retries with exponential backoff

The callback is best-effort. Always treat /run/:id/details as the source of truth. Use watchers to trigger your workflow, then fetch the full details.

---

Production polling pattern

For production use, wrap polling in a timeout:

cURL

# Poll until status is "completed"
while true; do
  STATUS=$(curl -s "https://api.case.dev/agent/v1/run/$RUN_ID/status" \
    -H "Authorization: Bearer $CASEDEV_API_KEY" | jq -r '.status')
  case "$STATUS" in
    completed) break ;;
    failed|cancelled) echo "Run $STATUS"; exit 1 ;;
    *) sleep 3 ;;
  esac
done

# Get full results
curl -s "https://api.case.dev/agent/v1/run/$RUN_ID/details" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Next: Sandbox environment

Learn what tools and capabilities are available inside the sandbox →