> ## 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/{id} — full session detail and events

> Retrieve full detail for a single session: redaction events, per-category detection counts, stage latencies, and Merkle root for audit verification.

Returns complete detail for a single session, including every individual redaction event with span coordinates, confidence scores, and token metadata. This is the endpoint to use when you need to investigate a specific call, verify what PHI was detected, or pull the `merkle_root_hex` for audit chain-of-custody verification.

If `log_payloads: true` is set in the agent's masking policy, the response also includes the original request, masked payload sent to the LLM, and the final response. Payloads are `null` by default.

## Endpoint

```
GET /api/v1/sessions/{session_id}
```

Requires `masker_session` authentication.

## Path parameters

<ParamField path="session_id" type="string" required>
  The session's ID in `sess_*` ULID format, e.g. `sess_01HYZ...`.
</ParamField>

## Response fields

<ResponseField name="session" type="object" required>
  Full session object.

  <Expandable title="session object fields" defaultOpen>
    <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.
    </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: `ok`, `error`, or `partial`.
    </ResponseField>

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

    <ResponseField name="policy_name" type="string" required>
      Name of the masking policy active at the time of the session.
    </ResponseField>

    <ResponseField name="policy_version" type="number" required>
      Version of the masking policy active at the time of the session.
    </ResponseField>

    <ResponseField name="stage_durations_ms" type="object" required>
      Breakdown of processing latency by pipeline stage.

      <Expandable title="stage duration fields">
        <ResponseField name="detection" type="number">
          Time spent on PHI detection in milliseconds.
        </ResponseField>

        <ResponseField name="tokenize" type="number">
          Time spent on tokenization (vault operations) in milliseconds.
        </ResponseField>

        <ResponseField name="upstream" type="number">
          Time spent waiting for the upstream LLM in milliseconds.
        </ResponseField>

        <ResponseField name="rehydrate" type="number">
          Time spent on token rehydration in the response in milliseconds.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="events" type="object[]" required>
      Array of individual redaction events for this session.

      <Expandable title="event fields">
        <ResponseField name="event_id" type="string">
          Event ID in `evt_*` ULID format.
        </ResponseField>

        <ResponseField name="pass" type="string">
          Detection pass that identified this entity (e.g. `gemma`).
        </ResponseField>

        <ResponseField name="entity_kind" type="string">
          PHI category, e.g. `NAME`, `PHONE`, `DOB`, `SSN`.
        </ResponseField>

        <ResponseField name="span" type="number[]">
          `[start, end]` character offsets in the original message.
        </ResponseField>

        <ResponseField name="confidence" type="number">
          Model confidence score from 0 to 1.
        </ResponseField>

        <ResponseField name="token_kind" type="string">
          Tokenization format applied, e.g. `MSKV1`.
        </ResponseField>

        <ResponseField name="kid" type="string">
          Key ID used to issue the token, e.g. `K_HEALTHCARE`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="payloads" type="object" required>
      Raw payloads. All fields are `null` unless `log_payloads: true` is set in the agent's policy.

      <Expandable title="payload fields">
        <ResponseField name="request">Original request body received by the proxy.</ResponseField>
        <ResponseField name="masked">Masked request body forwarded to the upstream LLM.</ResponseField>
        <ResponseField name="response">Final response returned to the caller, with tokens rehydrated.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -H "Cookie: masker_session=ey..." \
    https://masker-voice.fly.dev/api/v1/sessions/sess_01HYZ...
  ```
</CodeGroup>

```json Response theme={null}
{
  "session": {
    "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",
    "upstream_model": "gpt-4o-mini",
    "policy_name": "healthcare-default",
    "policy_version": 1,
    "stage_durations_ms": {
      "detection": 56,
      "tokenize": 4,
      "upstream": 728,
      "rehydrate": 6
    },
    "events": [
      {
        "event_id": "evt_01HYZ...",
        "pass": "gemma",
        "entity_kind": "NAME",
        "span": [142, 156],
        "confidence": 0.94,
        "token_kind": "MSKV1",
        "kid": "K_HEALTHCARE"
      }
    ],
    "payloads": {
      "request": null,
      "masked": null,
      "response": null
    }
  }
}
```

## Errors

| Status | Code                | Meaning                                        |
| ------ | ------------------- | ---------------------------------------------- |
| `401`  | `unauthenticated`   | Missing or invalid `masker_session` cookie     |
| `404`  | `session_not_found` | No session with this ID exists in your account |