> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caged.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> View agent sessions and their metrics.

# Sessions

Sessions represent individual agent interactions with a sandbox.

## List Sessions

```bash theme={null}
curl https://api.caged.dev/v1/sandboxes/cage-a1b2c3d4/sessions \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json theme={null}
[
  {
    "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

```bash theme={null}
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.

```bash theme={null}
curl https://api.caged.dev/v1/sessions/sess-a1b2c3d4/replay \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json theme={null}
{
  "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

```bash theme={null}
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.

```bash theme={null}
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`

```json theme={null}
{ "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`.