Sessions

Sessions represent individual agent interactions with a sandbox.

List Sessions

curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/sessions \
  -H "Authorization: Bearer caged_sk_..."

Response 200 OK

[
  {
    "id": "sess-a1b2c3d4",
    "sandbox_id": "cage-a1b2c3d4",
    "status": "completed",
    "agent_type": "claude-code",
    "model": "claude-sonnet-4-20250514",
    "tokens_in": 15420,
    "tokens_out": 8230,
    "cost_usd": 0.0847,
    "trust_score": 92,
    "duration_ms": 45200,
    "started_at": "2026-06-08T10:00:00Z",
    "ended_at": "2026-06-08T10:00:45Z"
  }
]

Session Fields

Field	Type	Description
`id`	string	Unique session ID
`sandbox_id`	string	Associated sandbox
`status`	string	`active`, `completed`, `failed`, `timeout`
`agent_type`	string	Agent identifier
`model`	string	LLM model used
`tokens_in`	integer	Total input tokens
`tokens_out`	integer	Total output tokens
`cost_usd`	number	Total cost (LLM + compute)
`trust_score`	integer	Behavioral trust score (0-100)
`event_count`	integer	Number of recorded events
`duration_ms`	integer	Session duration in milliseconds
`started_at`	string	ISO 8601 start time
`ended_at`	string	ISO 8601 end time

Get Session

curl https://api.caged.dev/v1/sessions/sess-a1b2c3d4 \
  -H "Authorization: Bearer caged_sk_..."

Returns a single session object (same shape as the list items above).

Get Session Replay

Returns the ordered event timeline for a session.

curl https://api.caged.dev/v1/sessions/sess-a1b2c3d4/replay \
  -H "Authorization: Bearer caged_sk_..."

Response 200 OK

{
  "events": [
    {
      "id": "7aa4a05a-9203-45ac-9e17-b8b7faf1ffe1",
      "session_id": "sess-a1b2c3d4",
      "sequence": 1781221257771341,
      "type": "command",
      "timestamp": "2026-06-11T23:40:57Z",
      "data": {
        "command": "echo hello",
        "exit_code": 0,
        "output": "hello\n"
      }
    }
  ],
  "has_more": false,
  "next_seq": 1781221257771341,
  "total": 1
}

Query params: after_seq (paginate; pass the previous response's next_seq), limit (default 100), type (filter by event type).

Get Replay Summary

curl https://api.caged.dev/v1/sessions/sess-a1b2c3d4/replay/summary \
  -H "Authorization: Bearer caged_sk_..."

Returns aggregate counts per event type, total duration, and the time range of the recording.

Ingest Events

Agents and SDKs push observability events in batches. The authenticated account is applied to every event server-side.

curl -X POST https://api.caged.dev/v1/events/ingest \
  -H "Authorization: Bearer caged_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "session_id": "9f1d2c3b-...",
        "sandbox_id": "cage-a1b2c3d4",
        "type": "llm_call",
        "timestamp": "2026-06-11T23:40:57Z",
        "meta": { "agent": "claude-code" },
        "payload": {
          "model": "claude-sonnet-4",
          "provider": "anthropic",
          "tokens_in": 1200,
          "tokens_out": 350,
          "cost_usd": 0.0145
        }
      }
    ]
  }'

Response 200 OK

{ "accepted": 1, "errors": 0 }

Limits: max 1000 events per request, 4 MB body. Event types: llm_call, tool_call, file_op, command, network, error, lifecycle.

Was this page helpful?