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

# Sessions

> List and retrieve session recordings

## List Sessions

Retrieve a paginated list of Claude Code sessions.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  "https://api.prod.turen.io/api/v1/sessions?limit=20"
```

### Query Parameters

| Parameter           | Type    | Default | Description                  |
| ------------------- | ------- | ------- | ---------------------------- |
| `limit`             | number  | 20      | Number of sessions to return |
| `offset`            | number  | 0       | Pagination offset            |
| `agent_id`          | string  | -       | Filter by agent ID           |
| `client_id`         | string  | -       | Filter by client ID          |
| `project`           | string  | -       | Filter by project path       |
| `git_branch`        | string  | -       | Filter by git branch         |
| `date`              | string  | -       | Filter by date (YYYY-MM-DD)  |
| `tz`                | string  | -       | Timezone for date filtering  |
| `include_subagents` | boolean | false   | Include subagent sessions    |

### Response

```json theme={null}
{
  "sessions": [
    {
      "id": 123,
      "session_id": "sess_abc123",
      "client_id": "a1b2c3d4e5f67890",
      "agent_hostname": "johns-macbook-pro",
      "project_path": "/Users/john/project",
      "first_prompt": "Help me refactor the auth module",
      "git_branch": "feature/auth-refactor",
      "message_count": 23,
      "created_at": "2026-02-17T09:00:00Z",
      "modified_at": "2026-02-17T09:45:00Z",
      "uploaded_at": "2026-02-17T09:46:00Z",
      "size_bytes": 45200,
      "is_subagent": false,
      "subagent_count": 2
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 847,
    "has_more": true
  }
}
```

### Response Fields

| Field            | Type    | Description                            |
| ---------------- | ------- | -------------------------------------- |
| `id`             | number  | Database row ID                        |
| `session_id`     | string  | Claude Code session identifier         |
| `client_id`      | string  | Agent client ID                        |
| `agent_hostname` | string  | Machine hostname                       |
| `project_path`   | string  | Working directory path                 |
| `first_prompt`   | string  | First message in the session           |
| `git_branch`     | string  | Active git branch during the session   |
| `message_count`  | number  | Number of conversation messages        |
| `created_at`     | string  | When the session started               |
| `modified_at`    | string  | When the session last had activity     |
| `uploaded_at`    | string  | When the session was uploaded to Turen |
| `size_bytes`     | number  | Session data size                      |
| `is_subagent`    | boolean | Whether this is a subagent session     |
| `subagent_count` | number  | Number of subagent sessions spawned    |

## Get Session Detail

Retrieve metadata for a specific session.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/sessions/{id}
```

Returns the same fields as the list response for a single session.

## Download Session Content

Download the full decrypted session content.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/sessions/{id}/content
```

Returns the session as JSON:

```json theme={null}
{
  "session_id": "sess_abc123",
  "message_count": 23,
  "messages": [
    {"type": "user", "content": "Help me refactor the auth module", "timestamp": "2026-02-17T09:00:01Z"},
    {"type": "assistant", "content": "I'll start by reading the current auth implementation...", "timestamp": "2026-02-17T09:00:03Z"},
    {"type": "tool_use", "tool": "file_read", "path": "src/auth/index.ts", "timestamp": "2026-02-17T09:00:04Z"}
  ]
}
```

## Sessions Calendar

Get session counts grouped by date: useful for building calendar views.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  "https://api.prod.turen.io/api/v1/sessions/calendar?since=2026-02-01&until=2026-02-28"
```

### Response

```json theme={null}
{
  "days": [
    {"date": "2026-02-01", "count": 12},
    {"date": "2026-02-02", "count": 0},
    {"date": "2026-02-03", "count": 28}
  ],
  "total_count": 40
}
```

## List Session Clients

Get distinct clients with session counts.

```bash theme={null}
curl -H "X-API-Key: sk_live_your_key_here" \
  https://api.prod.turen.io/api/v1/sessions/clients
```