Sessions

Work with sessions in @arizeai/phoenix-client

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

Relevant Source Files

• src/sessions/listSessions.ts for the exact project selector shape

• src/sessions/getSessionTurns.ts for how turns are derived from root spans

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.

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.

Source Map

• src/sessions/listSessions.ts
• src/sessions/getSession.ts
• src/sessions/getSessionTurns.ts
• src/sessions/addSessionAnnotation.ts
• src/sessions/addSessionNote.ts
• src/sessions/deleteSession.ts
• src/sessions/deleteSessions.ts