Skip to main content
A trajectory is a record of how an agent ran from start to finish. It captures the user prompt, system instructions, the agent’s final response, and a detailed breakdown of every step and tool call in between. Use trajectories to understand what the agent did, debug unexpected results, and share run details with Poolside Support. The Trajectory Viewer in the Poolside Console is the same whether you open it from the IDE or from an agent’s session history in the Poolside Console.

​
Who can view trajectories

You can view a trajectory in any of the following cases:
  • You started the session yourself.
  • You have the View Agent Sessions permission for the agent that ran the session, or for all agents.
  • You have the Manage Agents permission for the agent that ran the session, or for all agents.
  • You belong to a team with the tenant-admin role.
For more information, see Permissions reference.

​
Open a trajectory

If you want the trajectory for the current session, run /trajectory in the Poolside Assistant chat panel. This opens the trajectory in the Poolside Console. To open the raw .jsonl file in your IDE instead, hold Option (macOS) or Alt (Windows and Linux) when selecting trajectory. If you are using pool code, type /share to get a URL for the current session in the web-based Trajectory Viewer. A session must already exist, so /share works only after you send at least one prompt. If you want to inspect trajectories stored locally by the pool CLI after a session, use pool history trajectories:
  • pool history trajectories lists recent trajectories.
  • pool history trajectories --all lists all locally stored trajectories.
  • pool history trajectories --latest prints the most recent trajectory.
  • pool history trajectories <filename-match> prints a trajectory whose filename contains the text you enter.
These commands read locally stored trajectory files, not server-side trajectory data. If you can review an agent’s session history in the Poolside Console, you can also open a trajectory by selecting a session from Agent auditing.

​
Review session details

The Trajectory Viewer displays high-level session information at the top of the page:
  • Status, start and end time, and duration
  • Whether errors occurred
  • The user prompt and system instructions applied during the session
  • The agent’s final response and session exit
  • Environment details such as editor, runtime, and platform
If the session is still active, the Trajectory Viewer reloads automatically to reflect new activity.

​
Review session flow

​
Steps tab

Use the Steps tab to understand what the agent did at a high level. Selecting a step updates the page URL, so you can share a link that opens the trajectory at that specific step.
  1. In the Trajectory Viewer, select the Steps tab.
  2. Review the sequence of steps in the session.
  3. Identify high-level actions such as reading files, editing content, recording state, or exiting the session.
  4. To filter the list to steps with errors, select the Show errors only checkbox.

​
Events tab

Use the Events tab to inspect the session in detail.
  1. In the Trajectory Viewer, select the Events tab.
  2. Review tool usage, agent messages, and other session events.
  3. Use search to filter events and locate specific details.

​
Time tab

Use the Time tab to identify where the session spent time.
  1. In the Trajectory Viewer, select the Time tab.
  2. Review tool calls grouped by type to identify patterns.
  3. Look for long-running commands, inference-heavy tool calls, and repeated calls with the same inputs.
  1. In the Trajectory Viewer, expand Multi-turn trajectory.
  2. Review the list of previous turns.
  3. Select See turn to open the Trajectory Viewer for a specific turn.

​
Export trajectory data

Export a trajectory as a JSON file to investigate agent behavior offline or share with Poolside Support for troubleshooting.
Trajectory exports can contain sensitive information, including file contents, environment variables, API keys, and personal or proprietary data.
  1. Open the session in the Trajectory Viewer.
  2. Click Download.
  3. In the Download Trajectory dialog, review the warning that the file may contain sensitive information.
  4. Click Download.