Sessions

The sessions module groups multi-turn activity under a project and supports retrieval, annotations, and cleanup.

List Sessions#

import { listSessions } from "@arizeai/phoenix-client/sessions";const sessions = await listSessions({  projectName: "support-bot",});for (const session of sessions) {  console.log({    sessionId: session.sessionId,    promptTokens: session.tokenCountPrompt,    completionTokens: session.tokenCountCompletion,    totalTokens: session.tokenCountTotal,  });}

Each session includes cumulative prompt, completion, and total token counts across all of its spans. The fields may be undefined when using a Phoenix server that does not return session token usage.

Pass a filter expression to narrow the results. The language is documented on the Filter Expressions page.

const failedSessions = await listSessions({  project: "support-bot",  filter: "num_traces_with_error > 0 and duration_ms >= 60000",});

Empty expressions do not filter. Invalid expressions return HTTP 400; older servers are rejected before sending an expression.

Retrieve A Session And Its Turns#

import {  getSession,  getSessionTurns,} from "@arizeai/phoenix-client/sessions";const session = await getSession({  sessionId: "cst_123",});const turns = await getSessionTurns({  sessionId: "cst_123",});

getSession() and getSessionTurns() only need sessionId. They do not take a project selector.

Annotate Sessions#

Session annotations are covered in depth in Session Annotations. Quick example:

import { addSessionAnnotation } from "@arizeai/phoenix-client/sessions";await addSessionAnnotation({  sessionAnnotation: {    sessionId: "cst_123",    name: "handoff-required",    annotatorKind: "CODE",    score: 1,    label: "yes",  },});

Add a Note to a Session#

Use addSessionNote to append a free-text note to a session. Multiple notes can be added to the same session; each receives a unique UUIDv4 identifier.

Requires Phoenix server >= 14.17.0.

import { addSessionNote } from "@arizeai/phoenix-client/sessions";const result = await addSessionNote({  sessionNote: {    sessionId: "cst_123",    note: "Needs review — retrieval returned empty results on turn 3",  },});console.log(result.id); // UUIDv4 for the created note

Cleanup#

Use deleteSession or deleteSessions when you need to remove session records by identifier.

Relevant Source Files

List Sessions#

Retrieve A Session And Its Turns#

Annotate Sessions#

Add a Note to a Session#

Cleanup#

Source Map