GET /agents/{id}/sessions — list sessions by agent

Returns sessions for a specific agent, ordered by start time (newest first). This endpoint is equivalent to GET /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

string

required

The agent’s ID in agt_* ULID format, e.g. agt_01HYZ....

Query parameters

number

default:"25"

Maximum number of sessions to return. Accepted range: 1–100.

string

Pagination cursor from a previous response’s next_cursor. Omit to start from the first page.

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.

string

Filter by session outcome. One of ok, error, or partial. Omit to return sessions of all statuses.

number

default:"0"

Return only sessions with at least this many PHI redactions.

Response fields

object[]

required

Array of session summary objects.

Show session summary fields

string

required

Session ID in sess_* ULID format.

string

required

ID of the agent that handled this session.

string

required

ISO 8601 UTC timestamp when the session started.

string

required

ISO 8601 UTC timestamp when the session ended.

number

required

Total session duration in milliseconds.

string

required

Outcome of the session: ok, error, or partial.

number

required

Total number of PHI detections redacted during this session.

object

required

Redaction counts broken down by PHI category, e.g. {"PHONE": 1, "NAME": 2, "DOB": 1}.

string | null

required

Cursor for the next page. null when you have reached the last page.

Example

curl -H "Cookie: masker_session=ey..." \
  "https://masker-voice.fly.dev/api/v1/agents/agt_01HYZ.../sessions?since=7d&limit=100"

Response

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

Overview

Agents

Sessions

Proxy & Webhooks

GET /agents/{id}/sessions — list sessions by agent

Endpoint

Path parameters

Query parameters

Response fields

Example

Errors

​Endpoint

​Path parameters

​Query parameters

​Response fields

​Example

​Errors

Endpoint

Path parameters

Query parameters

Response fields

Example

Errors