@arizeai/phoenix-client 6.0.0 → 6.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",

package/src/__generated__/api/v1.ts

@@ -1745,7 +1745,7 @@ export interface components {
          * ModelProvider
          * @enum {string}
          */
-        ModelProvider: "OPENAI" | "AZURE_OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "XAI" | "OLLAMA" | "AWS";
+        ModelProvider: "OPENAI" | "AZURE_OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "XAI" | "OLLAMA" | "AWS" | "CEREBRAS" | "FIREWORKS" | "GROQ" | "MOONSHOT";
         /** OAuth2User */
         OAuth2User: {
             /** Id */
@@ -2122,6 +2122,37 @@ export interface components {
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
         };
+        /** PromptCerebrasInvocationParameters */
+        PromptCerebrasInvocationParameters: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "cerebras";
+            cerebras: components["schemas"]["PromptCerebrasInvocationParametersContent"];
+        };
+        /** PromptCerebrasInvocationParametersContent */
+        PromptCerebrasInvocationParametersContent: {
+            /** Temperature */
+            temperature?: number;
+            /** Max Tokens */
+            max_tokens?: number;
+            /** Max Completion Tokens */
+            max_completion_tokens?: number;
+            /** Frequency Penalty */
+            frequency_penalty?: number;
+            /** Presence Penalty */
+            presence_penalty?: number;
+            /** Top P */
+            top_p?: number;
+            /** Seed */
+            seed?: number;
+            /**
+             * Reasoning Effort
+             * @enum {string}
+             */
+            reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+        };
         /** PromptChatTemplate */
         PromptChatTemplate: {
             /**
@@ -2175,6 +2206,37 @@ export interface components {
              */
             reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
         };
+        /** PromptFireworksInvocationParameters */
+        PromptFireworksInvocationParameters: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "fireworks";
+            fireworks: components["schemas"]["PromptFireworksInvocationParametersContent"];
+        };
+        /** PromptFireworksInvocationParametersContent */
+        PromptFireworksInvocationParametersContent: {
+            /** Temperature */
+            temperature?: number;
+            /** Max Tokens */
+            max_tokens?: number;
+            /** Max Completion Tokens */
+            max_completion_tokens?: number;
+            /** Frequency Penalty */
+            frequency_penalty?: number;
+            /** Presence Penalty */
+            presence_penalty?: number;
+            /** Top P */
+            top_p?: number;
+            /** Seed */
+            seed?: number;
+            /**
+             * Reasoning Effort
+             * @enum {string}
+             */
+            reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+        };
         /** PromptGoogleInvocationParameters */
         PromptGoogleInvocationParameters: {
             /**
@@ -2201,6 +2263,37 @@ export interface components {
             /** Top K */
             top_k?: number;
         };
+        /** PromptGroqInvocationParameters */
+        PromptGroqInvocationParameters: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "groq";
+            groq: components["schemas"]["PromptGroqInvocationParametersContent"];
+        };
+        /** PromptGroqInvocationParametersContent */
+        PromptGroqInvocationParametersContent: {
+            /** Temperature */
+            temperature?: number;
+            /** Max Tokens */
+            max_tokens?: number;
+            /** Max Completion Tokens */
+            max_completion_tokens?: number;
+            /** Frequency Penalty */
+            frequency_penalty?: number;
+            /** Presence Penalty */
+            presence_penalty?: number;
+            /** Top P */
+            top_p?: number;
+            /** Seed */
+            seed?: number;
+            /**
+             * Reasoning Effort
+             * @enum {string}
+             */
+            reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+        };
         /** PromptMessage */
         PromptMessage: {
             /**
@@ -2211,6 +2304,37 @@ export interface components {
             /** Content */
             content: string | (components["schemas"]["TextContentPart"] | components["schemas"]["ToolCallContentPart"] | components["schemas"]["ToolResultContentPart"])[];
         };
+        /** PromptMoonshotInvocationParameters */
+        PromptMoonshotInvocationParameters: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "moonshot";
+            moonshot: components["schemas"]["PromptMoonshotInvocationParametersContent"];
+        };
+        /** PromptMoonshotInvocationParametersContent */
+        PromptMoonshotInvocationParametersContent: {
+            /** Temperature */
+            temperature?: number;
+            /** Max Tokens */
+            max_tokens?: number;
+            /** Max Completion Tokens */
+            max_completion_tokens?: number;
+            /** Frequency Penalty */
+            frequency_penalty?: number;
+            /** Presence Penalty */
+            presence_penalty?: number;
+            /** Top P */
+            top_p?: number;
+            /** Seed */
+            seed?: number;
+            /**
+             * Reasoning Effort
+             * @enum {string}
+             */
+            reasoning_effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+        };
         /** PromptOllamaInvocationParameters */
         PromptOllamaInvocationParameters: {
             /**
@@ -2397,7 +2521,7 @@ export interface components {
             template_type: components["schemas"]["PromptTemplateType"];
             template_format: components["schemas"]["PromptTemplateFormat"];
             /** Invocation Parameters */
-            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"];
+            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"] | components["schemas"]["PromptCerebrasInvocationParameters"] | components["schemas"]["PromptFireworksInvocationParameters"] | components["schemas"]["PromptGroqInvocationParameters"] | components["schemas"]["PromptMoonshotInvocationParameters"];
             tools?: components["schemas"]["PromptTools"] | null;
             /** Response Format */
             response_format?: components["schemas"]["PromptResponseFormatJSONSchema"] | null;
@@ -2416,7 +2540,7 @@ export interface components {
             template_type: components["schemas"]["PromptTemplateType"];
             template_format: components["schemas"]["PromptTemplateFormat"];
             /** Invocation Parameters */
-            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"];
+            invocation_parameters: components["schemas"]["PromptOpenAIInvocationParameters"] | components["schemas"]["PromptAzureOpenAIInvocationParameters"] | components["schemas"]["PromptAnthropicInvocationParameters"] | components["schemas"]["PromptGoogleInvocationParameters"] | components["schemas"]["PromptDeepSeekInvocationParameters"] | components["schemas"]["PromptXAIInvocationParameters"] | components["schemas"]["PromptOllamaInvocationParameters"] | components["schemas"]["PromptAwsInvocationParameters"] | components["schemas"]["PromptCerebrasInvocationParameters"] | components["schemas"]["PromptFireworksInvocationParameters"] | components["schemas"]["PromptGroqInvocationParameters"] | components["schemas"]["PromptMoonshotInvocationParameters"];
             tools?: components["schemas"]["PromptTools"] | null;
             /** Response Format */
             response_format?: components["schemas"]["PromptResponseFormatJSONSchema"] | null;
@@ -4635,6 +4759,8 @@ export interface operations {
                 start_time?: string | null;
                 /** @description Exclusive upper bound time */
                 end_time?: string | null;
+                /** @description Filter by one or more trace IDs */
+                trace_id?: string[] | null;
             };
             header?: never;
             path: {
@@ -4694,6 +4820,8 @@ export interface operations {
                 start_time?: string | null;
                 /** @description Exclusive upper bound time */
                 end_time?: string | null;
+                /** @description Filter by one or more trace IDs */
+                trace_id?: string[] | null;
             };
             header?: never;
             path: {

package/src/sessions/getSession.ts

@@ -0,0 +1,44 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { Session } from "../types/sessions";
+import { toSession } from "./sessionUtils";
+
+export type GetSessionParams = ClientFn & {
+  /**
+   * The session identifier: either a GlobalID or user-provided session_id string.
+   */
+  sessionId: string;
+};
+
+/**
+ * Fetch a single session by its GlobalID or user-provided session_id string.
+ *
+ * @example
+ * ```ts
+ * import { getSession } from "@arizeai/phoenix-client/sessions";
+ *
+ * const session = await getSession({ sessionId: "my-session-id" });
+ * console.log(session.traces.length);
+ * ```
+ */
+export async function getSession({
+  client: _client,
+  sessionId,
+}: GetSessionParams): Promise<Session> {
+  const client = _client || createClient();
+  const { data, error } = await client.GET(
+    "/v1/sessions/{session_identifier}",
+    {
+      params: {
+        path: {
+          session_identifier: sessionId,
+        },
+      },
+    }
+  );
+  if (error) throw error;
+  invariant(data?.data, "Failed to get session");
+  return toSession(data.data);
+}

package/src/sessions/index.ts

@@ -1,2 +1,4 @@
 export * from "./addSessionAnnotation";
+export * from "./getSession";
+export * from "./listSessions";
 export * from "./logSessionAnnotations";

package/src/sessions/listSessions.ts

@@ -0,0 +1,64 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import type { Session } from "../types/sessions";
+import { toSession } from "./sessionUtils";
+
+export type ListSessionsParams = ClientFn & ProjectIdentifier;
+
+type SessionsResponse = components["schemas"]["GetSessionsResponseBody"];
+
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * List all sessions for a project with automatic pagination handling.
+ *
+ * @example
+ * ```ts
+ * import { listSessions } from "@arizeai/phoenix-client/sessions";
+ *
+ * const sessions = await listSessions({
+ *   project: "my-project",
+ * });
+ *
+ * for (const session of sessions) {
+ *   console.log(`Session: ${session.sessionId}, Traces: ${session.traces.length}`);
+ * }
+ * ```
+ */
+export async function listSessions(
+  params: ListSessionsParams
+): Promise<Session[]> {
+  const client = params.client || createClient();
+  const projectIdentifier = resolveProjectIdentifier(params);
+
+  const sessions: Session[] = [];
+  let cursor: string | null | undefined = null;
+
+  do {
+    const response: { data?: SessionsResponse; error?: unknown } =
+      await client.GET("/v1/projects/{project_identifier}/sessions", {
+        params: {
+          path: {
+            project_identifier: projectIdentifier,
+          },
+          query: {
+            cursor,
+            limit: DEFAULT_PAGE_SIZE,
+          },
+        },
+      });
+
+    if (response.error) throw response.error;
+    invariant(response.data?.data, "Failed to list sessions");
+
+    cursor = response.data.next_cursor ?? null;
+    sessions.push(...response.data.data.map(toSession));
+  } while (cursor != null);
+
+  return sessions;
+}

package/src/sessions/sessionUtils.ts

@@ -0,0 +1,23 @@
+import type { components } from "../__generated__/api/v1";
+import type { Session } from "../types/sessions";
+
+type SessionData = components["schemas"]["SessionData"];
+
+/**
+ * Convert an API SessionData response to a user-facing Session object.
+ */
+export function toSession(data: SessionData): Session {
+  return {
+    id: data.id,
+    sessionId: data.session_id,
+    projectId: data.project_id,
+    startTime: data.start_time,
+    endTime: data.end_time,
+    traces: data.traces.map((trace) => ({
+      id: trace.id,
+      traceId: trace.trace_id,
+      startTime: trace.start_time,
+      endTime: trace.end_time,
+    })),
+  };
+}

package/src/spans/getSpanAnnotations.ts

@@ -1,14 +1,15 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import type { ClientFn } from "../types/core";
-import type { ProjectSelector } from "../types/projects";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
 
 /**
  * Parameters to get span annotations from a project using auto-generated types
  */
 export interface GetSpanAnnotationsParams extends ClientFn {
   /** The project to get span annotations from */
-  project: ProjectSelector;
+  project: ProjectIdentifier;
   /** One or more span IDs to fetch annotations for */
   spanIds: string[];
   /** Optional list of annotation names to include. If provided, only annotations with these names will be returned. 'note' annotations are excluded by default unless explicitly included in this list. */
@@ -89,8 +90,7 @@ export async function getSpanAnnotations({
   limit = 100,
 }: GetSpanAnnotationsParams): Promise<GetSpanAnnotationsResult> {
   const client = _client ?? createClient();
-  const projectIdentifier =
-    "projectId" in project ? project.projectId : project.projectName;
+  const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<
     operations["listSpanAnnotationsBySpanIds"]["parameters"]["query"]

package/src/spans/getSpans.ts

@@ -1,14 +1,15 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import type { ClientFn } from "../types/core";
-import type { ProjectSelector } from "../types/projects";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
 
 /**
  * Parameters to get spans from a project using auto-generated types
  */
 export interface GetSpansParams extends ClientFn {
   /** The project to get spans from */
-  project: ProjectSelector;
+  project: ProjectIdentifier;
   /** Inclusive lower bound time. Must be a valid ISO 8601 string or Date object. */
   startTime?: Date | string | null;
   /** Exclusive upper bound time. Must be a valid ISO 8601 string or Date object. */
@@ -17,6 +18,8 @@ export interface GetSpansParams extends ClientFn {
   cursor?: string | null;
   /** Maximum number of spans to return */
   limit?: number;
+  /** Filter spans by one or more trace IDs */
+  traceIds?: string[] | null;
 }
 
 export type GetSpansResponse = operations["getSpans"]["responses"]["200"];
@@ -58,6 +61,13 @@ export type GetSpansResult = {
  *   limit: 100
  * });
 
+ *
+ * // Get all spans for specific traces (requires Phoenix server >= 13.9.0)
+ * const result = await getSpans({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   traceIds: ["trace-abc-123", "trace-def-456"],
+ * });
  *
  * // Paginate through results
  * let cursor: string | undefined;
@@ -85,10 +95,10 @@ export async function getSpans({
   limit = 100,
   startTime,
   endTime,
+  traceIds,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
-  const projectIdentifier =
-    "projectId" in project ? project.projectId : project.projectName;
+  const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {
     limit,
@@ -107,6 +117,10 @@ export async function getSpans({
     params.end_time = endTime instanceof Date ? endTime.toISOString() : endTime;
   }
 
+  if (traceIds) {
+    params.trace_id = traceIds;
+  }
+
   const { data, error } = await client.GET(
     "/v1/projects/{project_identifier}/spans",
     {

package/src/types/projects.ts

@@ -1,5 +1,22 @@
 /**
- * A project can be identified by its projectId or projectName
- * In the case of a projectName, the name must be url encodable
+ * Identifies a project. Accepts any of:
+ * - `project` — a project ID or name (the server accepts either)
+ * - `projectId` — an explicit project ID
+ * - `projectName` — an explicit project name
  */
-export type ProjectSelector = { projectId: string } | { projectName: string };
+export type ProjectIdentifier =
+  | { project: string }
+  | { projectId: string }
+  | { projectName: string };
+
+/**
+ * Resolves a {@link ProjectIdentifier} union to a plain string
+ * suitable for the REST `project_identifier` path parameter.
+ */
+export function resolveProjectIdentifier(
+  identifier: ProjectIdentifier
+): string {
+  if ("project" in identifier) return identifier.project;
+  if ("projectId" in identifier) return identifier.projectId;
+  return identifier.projectName;
+}

package/src/types/sessions.ts

@@ -0,0 +1,29 @@
+import type { Node } from "./core";
+
+/**
+ * A trace that belongs to a session.
+ */
+export interface SessionTrace extends Node {
+  /** The unique trace identifier (e.g. OpenTelemetry trace ID) */
+  traceId: string;
+  /** ISO 8601 timestamp of when the trace started */
+  startTime: string;
+  /** ISO 8601 timestamp of when the trace ended */
+  endTime: string;
+}
+
+/**
+ * A session representing a group of related traces (e.g. a multi-turn conversation).
+ */
+export interface Session extends Node {
+  /** The user-provided session identifier */
+  sessionId: string;
+  /** The ID of the project this session belongs to */
+  projectId: string;
+  /** ISO 8601 timestamp of when the first trace in the session started */
+  startTime: string;
+  /** ISO 8601 timestamp of when the last trace in the session ended */
+  endTime: string;
+  /** The traces that belong to this session */
+  traces: SessionTrace[];
+}