Inspect session

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.
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

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.

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:

export SESSION_ID="<session-id-from-the-list>"

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.

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

Retrieve transcript

Messages are stored separately from session metadata. Retrieve them in one call by session ID.

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.

Get started

Work with agents

Reference

Before you begin

Inspect your sessions

See also

​Before you begin

​Inspect your sessions

​See also

Before you begin

Inspect your sessions

See also