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

# GET /sessions — list call sessions across all agents

> List call sessions across every agent in your account. Filter by agent, status, time range, or minimum redaction count. Supports cursor pagination.

Returns session summaries across all agents in your account, ordered by start time (newest first). Use this endpoint to get a cross-agent view of activity, build dashboards, or export session metadata for compliance workflows. To list sessions for a single agent, you can either pass `agent_id` here or use [GET /agents/{id}/sessions](/api-reference/agents/list-agent-sessions).

## Endpoint

```
GET /api/v1/sessions
```

Requires `masker_session` authentication.

## Query parameters

<ParamField query="limit" type="number" default="25">
  Maximum number of sessions to return. Accepted range: 1–100.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response's `next_cursor`. Omit to start from the first page.
</ParamField>

<ParamField query="since" type="string" default="24h">
  Return only sessions that started within this window. Accepts a duration string (`1h`, `24h`, `7d`, `30d`) or an ISO 8601 UTC timestamp.
</ParamField>

<ParamField query="agent_id" type="string">
  Filter results to sessions handled by this specific agent. Accepts an `agt_*` ULID.
</ParamField>

<ParamField query="status" type="string">
  Filter by session outcome. One of `ok`, `error`, or `partial`. Omit to return sessions of all statuses.
</ParamField>

<ParamField query="min_redactions" type="number" default="0">
  Return only sessions with at least this many PHI redactions.
</ParamField>

## Response fields

<ResponseField name="data" type="object[]" required>
  Array of session summary objects.

  <Expandable title="session summary fields">
    <ResponseField name="id" type="string" required>
      Session ID in `sess_*` ULID format.
    </ResponseField>

    <ResponseField name="agent_id" type="string" required>
      ID of the agent that handled this session.
    </ResponseField>

    <ResponseField name="agent_name" type="string" required>
      Display name of the agent that handled this session.
    </ResponseField>

    <ResponseField name="started_at" type="string" required>
      ISO 8601 UTC timestamp when the session started.
    </ResponseField>

    <ResponseField name="ended_at" type="string" required>
      ISO 8601 UTC timestamp when the session ended.
    </ResponseField>

    <ResponseField name="duration_ms" type="number" required>
      Total session duration in milliseconds.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Outcome of the session: `ok`, `error`, or `partial`.
    </ResponseField>

    <ResponseField name="redaction_count" type="number" required>
      Total PHI detections redacted during this session.
    </ResponseField>

    <ResponseField name="redactions_by_kind" type="object" required>
      Redaction counts per PHI category, e.g. `{"PHONE": 1, "NAME": 2, "DOB": 1}`.
    </ResponseField>

    <ResponseField name="upstream_model" type="string" required>
      The LLM model used for this session, e.g. `gpt-4o-mini`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string | null" required>
  Cursor for the next page. `null` when you have reached the last page.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -H "Cookie: masker_session=ey..." \
    "https://masker-voice.fly.dev/api/v1/sessions?since=24h&limit=50"
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "id": "sess_01HYZ...",
      "agent_id": "agt_01HYZ...",
      "agent_name": "appointment-bot-prod",
      "started_at": "2026-05-03T21:14:32Z",
      "ended_at": "2026-05-03T21:14:32.794Z",
      "duration_ms": 794,
      "status": "ok",
      "redaction_count": 4,
      "redactions_by_kind": {"PHONE": 1, "NAME": 2, "DOB": 1},
      "upstream_model": "gpt-4o-mini"
    }
  ],
  "next_cursor": "eyJ..."
}
```

## Errors

| Status | Code                | Meaning                                    |
| ------ | ------------------- | ------------------------------------------ |
| `401`  | `unauthenticated`   | Missing or invalid `masker_session` cookie |
| `422`  | `validation_failed` | Bad query parameter value                  |