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

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.

# Inspect session

> List sessions for an agent, read a session by ID, and explore its transcript and metadata.

Every session the Registry holds is readable by ID. This guide shows you how
to list sessions for a registered agent, read a single session's metadata, and
retrieve its full transcript.

## Before you begin

Before you start, make sure you have:

* **Bearer credential and shell variables**: `ATLAN_GATEWAY_URL` and
  `ATLAN_TOKEN` set in your shell. See
  [Connect to Agent Registry](/api/tutorials/quickstart#prepare-your-shell).
* **Agent ID**: The `AGENT_ID` of a registered agent whose sessions you want
  to inspect.
* **Session ID** (optional): If you already know which session to read, export
  `SESSION_ID` now. If not, the first step below retrieves it.

## Inspect your sessions

<Steps>
  <Step title="List sessions for your agent">
    Filter sessions by agent to see all runs the Registry has recorded for it.
    Pass `subject_kind` and `subject_id` as query parameters.

    ```js theme={null}
    const sessions = await atlan(
      `/agent/v1/sessions?subject_kind=agent&subject_id=${process.env.AGENT_ID}`
    );

    console.log(sessions);
    ```

    The response is a paginated list. Each item includes the session `id`,
    `name`, `session_status`, `model_id`, `stop_reason`, and `source_created_at`.
    Pick the session ID you want to inspect and set it:

    ```bash theme={null}
    export SESSION_ID="<session-id-from-the-list>"
    ```
  </Step>

  <Step title="Read session metadata">
    A session record holds everything about the run except its messages:
    which agent ran, which model was used, how it ended, and when it happened.

    ```js theme={null}
    const session = await atlan(`/agent/v1/sessions/${process.env.SESSION_ID}`);
    console.log(session);
    ```

    Key fields to look at:

    | Field | What it tells you |
    | - | - |
    | `session_status` | How the run ended: `completed`, `failed`, or `running` |
    | `stop_reason` | Why the model stopped: `end_turn`, `max_tokens`, `tool_use`, etc. |
    | `model_id` | Which model the agent used |
    | `source_created_at` | When the run actually happened (not when it was recorded) |
    | `subject_id` | The agent this session belongs to |
  </Step>

  <Step title="Retrieve transcript">
    Messages are stored separately from session metadata. Retrieve them in one
    call by session ID.

    ```js theme={null}
    const messages = await atlan(
      `/agent/v1/sessions/${process.env.SESSION_ID}/messages`
    );

    console.log(messages);
    ```

    Messages are ordered by `sequence_number`. Each message has a
    `message_role` (`user` or `assistant`) and a `content` field with the
    turn text.

    Confirm the message count, roles, and order match what you expect. If
    messages are missing, check whether they were recorded with the correct
    `session_id` path and `sequence_number`.
  </Step>
</Steps>

## See also

[Work with agents](/cookbooks/how-tos/agents): explore the full agent and
session API, including status filtering, bulk operations, and the session
lifecycle.

[Errors and retries](/platform/references/errors-and-retries): error codes,
causes, and when to retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.