Agent Session REST API#

Phoenix exposes two REST endpoints for listing and retrieving persisted agent sessions. These routes were added in PR #14711 1 and are implemented in src/phoenix/server/api/routers/agents.py. They are distinct from the GraphQL interface, which gates access via the CanAccessAgentSession permission class in src/phoenix/server/api/agent_helpers.py 2.

Both endpoints return only persisted (non-temporary, non-expired) sessions.

Endpoints#

List Sessions — GET /agents/{agent_id}/sessions#

Query parameters:

• cursor (optional): opaque pagination cursor
• limit (optional, default 20, max 100)

Response — ListAgentSessionsResponseBody:

• data: array of AgentSessionSummary objects — fields: id, title, created_at, updated_at, is_temporary
• next_cursor: pagination cursor for the next page; null if no further results

Get Session — GET /agents/{agent_id}/sessions/{session_id}#

Response — GetAgentSessionResponseBody:

• data: an AgentSessionData object — all AgentSessionSummary fields plus messages, an array of PhoenixUIMessage objects (id, role, parts[])

Returns 404 if the session is expired or owned by another user 2.

Cursor-Based Pagination#

Pagination uses a keyset strategy sorted by (updated_at DESC, id DESC) for stable ordering. The cursor encodes both sort values as an opaque token 1. The _parse_agent_session_cursor() utility deserializes and validates the cursor; a malformed cursor returns HTTP 422.

Access Control and User Scoping#

The helper _get_request_user_id(request) extracts the authenticated user's ID from the request 2:

• Auth enabled → queries are filtered to AgentSession.user_id == <request user>. Users only see their own sessions.
• Auth disabled → all persisted sessions for the agent are returned.

This is applied in both the list endpoint and the single-session endpoint. The GraphQL layer enforces equivalent scoping through get_agent_session_owner_filter() in agent_helpers.py 2.

Testing#

• Unit tests: tests/unit/server/agents/test_agent_session_routes.py (201 lines, new file in PR #14711) — covers pagination limits, cursor round-trips, temporary vs. persisted session filtering, and expiry handling 1.
• Integration tests: tests/integration/auth/test_auth.py — verifies that a member API key can only list/retrieve its own sessions and receives 404 for another user's sessions 2.

PXI CLI Integration#

The endpoints power the /sessions session picker in the pxi CLI — an inline searchable list for restoring persisted agent chats. They are consumed via the generated Phoenix client in js/packages/phoenix-cli/src/pxi/client.ts and App.tsx 3. The PR also introduced /new, /temporary, and /clear session lifecycle commands alongside the session picker.

Generated Clients and Schema#

The REST routes are defined in schemas/openapi.json (+241 lines) and auto-generated into typed clients 1: