> ## 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 /agents/{id}/sessions — list sessions by agent

> List call sessions scoped to a single agent, with filters for time range, status, and minimum redaction count. Supports cursor pagination.

Returns sessions for a specific agent, ordered by start time (newest first). This endpoint is equivalent to [GET /sessions](/api-reference/sessions/list-sessions) with `agent_id` pre-applied, but also supports additional agent-scoped filters like `min_redactions`. Use it to audit activity for a single agent without having to filter a cross-account session list.

## Endpoint

```
GET /api/v1/agents/{agent_id}/sessions
```

Requires `masker_session` authentication.

## Path parameters

<ParamField path="agent_id" type="string" required>
  The agent's ID in `agt_*` ULID format, e.g. `agt_01HYZ...`.
</ParamField>

## 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="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="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 number of PHI detections redacted during this session.
    </ResponseField>

    <ResponseField name="redactions_by_kind" type="object" required>
      Redaction counts broken down by PHI category, e.g. `{"PHONE": 1, "NAME": 2, "DOB": 1}`.
    </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/agents/agt_01HYZ.../sessions?since=7d&limit=100"
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "id": "sess_01HYZ...",
      "agent_id": "agt_01HYZ...",
      "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}
    }
  ],
  "next_cursor": "eyJ..."
}
```

## Errors

| Status | Code                | Meaning                                           |
| ------ | ------------------- | ------------------------------------------------- |
| `401`  | `unauthenticated`   | Missing or invalid `masker_session` cookie        |
| `404`  | `agent_not_found`   | No agent with this ID exists in your account      |
| `422`  | `validation_failed` | Bad query parameter value, e.g. malformed `since` |