---
title: Sessions
description: "View agent sessions and their metrics."
---

# Sessions

Sessions represent individual agent interactions with a sandbox.

## List Sessions

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

**Response** `200 OK`

```json
[
  {
    "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
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
curl https://api.caged.dev/v1/sessions/sess-a1b2c3d4/replay \
  -H "Authorization: Bearer caged_sk_..."
```

**Response** `200 OK`

```json
{
  "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
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
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
{ "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`.