@arizeai/phoenix-client 7.10.0 → 7.12.0

package/docs/sessions.mdx

@@ -42,6 +42,19 @@ Each session includes cumulative prompt, completion, and total token counts acro
 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](/docs/phoenix/tracing/how-to-tracing/filter-expressions) page.
+
+```ts
+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
 
 ```ts

package/docs/traces.mdx

@@ -60,16 +60,16 @@ console.log(result.nextCursor);
 - `cursor`
 - `includeSpans`
 - `sessionId`
-- `error`
-- `minLatencyMs`
-- `maxLatencyMs`
+- `filter` — a trace DSL expression, combined with other filters using AND
+- `error` (deprecated; use `filter`)
+- `minLatencyMs` (deprecated; use `filter`)
+- `maxLatencyMs` (deprecated; use `filter`)
 
 ```ts
 // Slow traces that contain at least one errored span
 const slowFailures = await getTraces({
   project: { projectName: "support-bot" },
-  error: true,
-  minLatencyMs: 1000,
+  filter: "error_count > 0 and latency_ms >= 1000",
 });
 ```
 
@@ -79,7 +79,8 @@ const slowFailures = await getTraces({
 - Use the returned `nextCursor` to continue pagination
 - Set `includeSpans` when you need a trace-centric fetch that also contains span details
 - `project` accepts `{ project }`, `{ projectId }`, or `{ projectName }`
-- `error`, `minLatencyMs`, and `maxLatencyMs` require Phoenix server >= 20.8.0; `error: false` selects traces with no errored spans
+- `filter` takes a trace filter expression; the language is documented on the [Filter Expressions](/docs/phoenix/tracing/how-to-tracing/filter-expressions) page, and its [Finding field names](/docs/phoenix/tracing/how-to-tracing/filter-expressions#finding-field-names) section covers discovering valid names for your project.
+- `error`, `minLatencyMs`, and `maxLatencyMs` remain supported on Phoenix server >= 20.8.0. Replace them with `error_count > 0` / `error_count == 0`, `latency_ms >= N`, and `latency_ms <= N` respectively. Latency bounds are inclusive and errors include child spans.
 
 ## Move Traces To Another Project
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.10.0",
+  "version": "7.12.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -103,31 +103,31 @@
     }
   },
   "dependencies": {
-    "@arizeai/openinference-semantic-conventions": "^2.7.0",
+    "@arizeai/openinference-semantic-conventions": "^2.12.0",
     "@arizeai/phoenix-config": "0.5.0",
     "@arizeai/phoenix-otel": "2.2.0",
     "async": "^3.2.6",
     "openapi-fetch": "^0.17.0",
     "tiny-invariant": "^1.3.3",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^4.0.46",
-    "@ai-sdk/otel": "^1.0.77",
+    "@ai-sdk/openai": "^4.0.71",
+    "@ai-sdk/otel": "^1.0.107",
     "@anthropic-ai/sdk": "^0.111.0",
-    "@arizeai/phoenix-evals": "2.4.0",
+    "@arizeai/phoenix-evals": "2.5.0",
     "@arizeai/phoenix-testing": "0.0.0",
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/sdk-trace-node": "^2.10.0",
-    "@types/async": "^3.2.25",
-    "@types/node": "^26.2.0",
-    "ai": "^7.0.77",
+    "@opentelemetry/sdk-trace-node": "^2.11.0",
+    "@types/async": "^3.2.26",
+    "@types/node": "^26.6.2",
+    "ai": "^7.0.107",
     "dotenv": "^17.4.2",
-    "jest": "^30.4.2",
+    "jest": "^30.5.2",
     "openai": "^6.49.0",
     "openapi-typescript": "^7.13.0",
-    "tsx": "^4.23.12",
-    "vitest": "^5.0.0"
+    "tsx": "^4.23.13",
+    "vitest": "^5.0.1"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.35.0",

package/src/__generated__/api/v1.ts

@@ -430,7 +430,8 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /** List dataset splits */
+        get: operations["listDatasetSplits"];
         put?: never;
         /** Create a dataset split */
         post: operations["createDatasetSplit"];
@@ -3980,6 +3981,13 @@ export interface components {
             /** Data */
             data: components["schemas"]["DatasetLabel"][];
         };
+        /** ListDatasetSplitsResponseBody */
+        ListDatasetSplitsResponseBody: {
+            /** Data */
+            data: components["schemas"]["DatasetSplit"][];
+            /** Next Cursor */
+            next_cursor: string | null;
+        };
         /** ListDatasetVersionsResponseBody */
         ListDatasetVersionsResponseBody: {
             /** Data */
@@ -5296,6 +5304,13 @@ export interface components {
         PromptVersion: {
             /** Description */
             description?: string | null;
+            /**
+             * Metadata
+             * @description Arbitrary JSON metadata for the prompt version.
+             */
+            metadata?: {
+                [key: string]: unknown;
+            };
             model_provider: components["schemas"]["ModelProvider"];
             /** Model Name */
             model_name: string;
@@ -5315,6 +5330,13 @@ export interface components {
         PromptVersionData: {
             /** Description */
             description?: string | null;
+            /**
+             * Metadata
+             * @description Arbitrary JSON metadata for the prompt version.
+             */
+            metadata?: {
+                [key: string]: unknown;
+            };
             model_provider: components["schemas"]["ModelProvider"];
             /** Model Name */
             model_name: string;
@@ -8945,6 +8967,61 @@ export interface operations {
             };
         };
     };
+    listDatasetSplits: {
+        parameters: {
+            query?: {
+                /** @description Cursor for pagination */
+                cursor?: string | null;
+                /** @description The max number of dataset splits to return at a time. */
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                /** @description The dataset identifier: either dataset ID or dataset name. */
+                dataset_identifier: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ListDatasetSplitsResponseBody"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Dataset not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Invalid request */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+        };
+    };
     createDatasetSplit: {
         parameters: {
             query?: never;
@@ -10098,12 +10175,23 @@ export interface operations {
                 include_spans?: boolean;
                 /** @description List of session identifiers to filter traces by. Each value can be either a session_id string or a session GlobalID. Only traces belonging to the specified sessions will be returned. */
                 session_identifier?: string[] | null;
-                /** @description Filter by trace error status. If true, only return traces that contain at least one span with `status_code == ERROR`. If false, only return traces with no errored spans. If omitted, traces are not filtered by error status. Matches the error indicator shown in the UI. */
+                /**
+                 * @deprecated
+                 * @description Deprecated: use `filter=error_count > 0` or `filter=error_count == 0`. Filter by trace error status. If true, only return traces that contain at least one span with `status_code == ERROR`. If false, only return traces with no errored spans. If omitted, traces are not filtered by error status.
+                 */
                 error?: boolean | null;
-                /** @description Inclusive lower bound on trace latency in milliseconds. */
+                /**
+                 * @deprecated
+                 * @description Inclusive lower bound on trace latency in milliseconds. Deprecated: use `filter=latency_ms >= N`.
+                 */
                 min_latency_ms?: number | null;
-                /** @description Inclusive upper bound on trace latency in milliseconds. */
+                /**
+                 * @deprecated
+                 * @description Inclusive upper bound on trace latency in milliseconds. Deprecated: use `filter=latency_ms <= N`.
+                 */
                 max_latency_ms?: number | null;
+                /** @description Trace filter expression, as documented at https://arize.com/docs/phoenix/tracing/how-to-tracing/filter-expressions. Combined with other filters using AND. Empty expressions do not filter. Invalid expressions return 400. */
+                filter?: string | null;
             };
             header?: never;
             path: {
@@ -10123,6 +10211,15 @@ export interface operations {
                     "application/json": components["schemas"]["GetTracesResponseBody"];
                 };
             };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
             /** @description Forbidden */
             403: {
                 headers: {
@@ -11890,6 +11987,8 @@ export interface operations {
                 limit?: number;
                 /** @description Sort order by ID: 'asc' (ascending) or 'desc' (descending). */
                 order?: "asc" | "desc";
+                /** @description Session filter expression, as documented at https://arize.com/docs/phoenix/tracing/how-to-tracing/filter-expressions. Empty expressions do not filter. Invalid expressions return 400. */
+                filter?: string | null;
             };
             header?: never;
             path: {
@@ -11909,6 +12008,15 @@ export interface operations {
                     "application/json": components["schemas"]["GetSessionsResponseBody"];
                 };
             };
+            /** @description Bad Request */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
             /** @description Forbidden */
             403: {
                 headers: {

package/src/constants/serverRequirements.ts

@@ -108,6 +108,22 @@ export const GET_TRACES_FILTERS: ParameterRequirement = {
     "The 'error', 'min_latency_ms', and 'max_latency_ms' query parameters on GET /v1/projects/{id}/traces",
 };
 
+export const GET_TRACES_FILTER_EXPRESSION: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "filter",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/traces",
+  minServerVersion: [20, 12, 0],
+};
+
+export const LIST_SESSIONS_FILTER_EXPRESSION: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "filter",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/sessions",
+  minServerVersion: [20, 12, 0],
+};
+
 export const TRANSFER_TRACES: RouteRequirement = {
   kind: "route",
   method: "POST",
@@ -245,6 +261,8 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
   GET_TRACES_FILTERS,
+  GET_TRACES_FILTER_EXPRESSION,
+  LIST_SESSIONS_FILTER_EXPRESSION,
   TRANSFER_TRACES,
   DATASET_UPLOAD_EXAMPLE_IDS,
   ADD_TRACE_NOTE_IDENTIFIER,

package/src/prompts/createPrompt.ts

@@ -84,6 +84,11 @@ interface PromptVersionInputBase {
    * The description of the prompt version.
    */
   description?: string;
+  /**
+   * Optional metadata for the prompt version as a JSON object.
+   * @example { "agent": "support", "dependencies": ["retriever"] }
+   */
+  metadata?: PromptVersionData["metadata"];
   /**
    * The name of the model to use for the prompt version.
    */
@@ -165,142 +170,51 @@ export type PromptVersionInput =
 export function promptVersion(params: PromptVersionInput): PromptVersionData {
   const {
     description = "",
+    metadata,
     modelProvider: model_provider,
     modelName: model_name,
     template: templateMessages,
     templateFormat: template_format = "MUSTACHE",
-    invocationParameters: invocation_parameters,
   } = params;
-  switch (model_provider) {
+  return {
+    description,
+    ...(metadata ? { metadata } : {}),
+    model_provider,
+    model_name,
+    template_type: "CHAT",
+    template_format,
+    template: {
+      type: "chat",
+      messages: templateMessages,
+    },
+    invocation_parameters: toInvocationParameters(params),
+  };
+}
+
+function toInvocationParameters(
+  params: PromptVersionInput
+): PromptVersionData["invocation_parameters"] {
+  switch (params.modelProvider) {
     case "OPENAI":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "openai",
-          openai: invocation_parameters ?? {},
-        },
-      };
+      return { type: "openai", openai: params.invocationParameters ?? {} };
     case "AZURE_OPENAI":
       return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "azure_openai",
-          azure_openai: invocation_parameters ?? {},
-        },
+        type: "azure_openai",
+        azure_openai: params.invocationParameters ?? {},
       };
     case "ANTHROPIC":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "anthropic",
-          anthropic: invocation_parameters,
-        },
-      };
+      return { type: "anthropic", anthropic: params.invocationParameters };
     case "GOOGLE":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "google",
-          google: invocation_parameters ?? {},
-        },
-      };
+      return { type: "google", google: params.invocationParameters ?? {} };
     case "DEEPSEEK":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "deepseek",
-          deepseek: invocation_parameters ?? {},
-        },
-      };
+      return { type: "deepseek", deepseek: params.invocationParameters ?? {} };
     case "XAI":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "xai",
-          xai: invocation_parameters ?? {},
-        },
-      };
+      return { type: "xai", xai: params.invocationParameters ?? {} };
     case "OLLAMA":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "ollama",
-          ollama: invocation_parameters ?? {},
-        },
-      };
+      return { type: "ollama", ollama: params.invocationParameters ?? {} };
     case "AWS":
-      return {
-        description,
-        model_provider,
-        model_name,
-        template_type: "CHAT",
-        template_format,
-        template: {
-          type: "chat",
-          messages: templateMessages,
-        },
-        invocation_parameters: {
-          type: "aws",
-          aws: invocation_parameters ?? {},
-        },
-      };
+      return { type: "aws", aws: params.invocationParameters ?? {} };
     default:
-      return assertUnreachable(model_provider);
+      return assertUnreachable(params);
   }
 }

package/src/sessions/listSessions.ts

@@ -2,7 +2,10 @@ import invariant from "tiny-invariant";
 
 import type { components } from "../__generated__/api/v1";
 import { createClient } from "../client";
-import { LIST_PROJECT_SESSIONS } from "../constants/serverRequirements";
+import {
+  LIST_PROJECT_SESSIONS,
+  LIST_SESSIONS_FILTER_EXPRESSION,
+} from "../constants/serverRequirements";
 import type { ClientFn } from "../types/core";
 import type { ProjectIdentifier } from "../types/projects";
 import { resolveProjectIdentifier } from "../types/projects";
@@ -10,7 +13,15 @@ import type { Session } from "../types/sessions";
 import { ensureServerCapability } from "../utils/serverVersionUtils";
 import { toSession } from "./sessionUtils";
 
-export type ListSessionsParams = ClientFn & ProjectIdentifier;
+export type ListSessionsParams = ClientFn &
+  ProjectIdentifier & {
+    /**
+     * Session filter expression.
+     * @see https://arize.com/docs/phoenix/tracing/how-to-tracing/filter-expressions
+     * @requires Phoenix server >= 20.12.0
+     */
+    filter?: string | null;
+  };
 
 type SessionsResponse = components["schemas"]["GetSessionsResponseBody"];
 
@@ -20,6 +31,8 @@ const DEFAULT_PAGE_SIZE = 100;
  * List all sessions for a project with automatic pagination handling.
  *
  * @requires Phoenix server >= 13.5.0
+ * @param params - Project and filtering options.
+ * @param params.filter - Session filter expression, passed unchanged on every page.
  *
  * @example
  * ```ts
@@ -39,6 +52,12 @@ export async function listSessions(
 ): Promise<Session[]> {
   const client = params.client || createClient();
   await ensureServerCapability({ client, requirement: LIST_PROJECT_SESSIONS });
+  if (params.filter) {
+    await ensureServerCapability({
+      client,
+      requirement: LIST_SESSIONS_FILTER_EXPRESSION,
+    });
+  }
   const projectIdentifier = resolveProjectIdentifier(params);
 
   const sessions: Session[] = [];
@@ -54,6 +73,7 @@ export async function listSessions(
           query: {
             cursor,
             limit: DEFAULT_PAGE_SIZE,
+            filter: params.filter || undefined,
           },
         },
       });

package/src/traces/getTraces.ts

@@ -1,6 +1,7 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import {
+  GET_TRACES_FILTER_EXPRESSION,
   GET_TRACES_FILTERS,
   LIST_PROJECT_TRACES,
 } from "../constants/serverRequirements";
@@ -31,22 +32,31 @@ export interface GetTracesParams extends ClientFn {
   includeSpans?: boolean;
   /** Filter traces by session identifier(s) (session_id strings or GlobalIDs) */
   sessionId?: string | string[] | null;
+  /**
+   * Trace filter expression, combined with other filters using AND.
+   * @see https://arize.com/docs/phoenix/tracing/how-to-tracing/filter-expressions
+   * @requires Phoenix server >= 20.12.0
+   */
+  filter?: string | null;
   /**
    * Filter by trace error status. `true` returns only traces containing at
    * least one errored span, `false` only traces with no errored spans.
    * Omit to leave traces unfiltered by error status.
+   * @deprecated Use `filter: "error_count > 0"` or `filter: "error_count == 0"`.
    *
    * @requires Phoenix server >= 20.8.0
    */
   error?: boolean | null;
   /**
    * Inclusive lower bound on trace latency in milliseconds.
+   * @deprecated Use `filter: "latency_ms >= N"`.
    *
    * @requires Phoenix server >= 20.8.0
    */
   minLatencyMs?: number | null;
   /**
    * Inclusive upper bound on trace latency in milliseconds.
+   * @deprecated Use `filter: "latency_ms <= N"`.
    *
    * @requires Phoenix server >= 20.8.0
    */
@@ -96,11 +106,15 @@ function buildQuery({
   order,
   includeSpans,
   sessionId,
+  filter,
   error,
   minLatencyMs,
   maxLatencyMs,
 }: Omit<GetTracesParams, "client" | "project">): ListProjectTracesQuery {
   const query: ListProjectTracesQuery = { limit };
+  if (filter) {
+    query.filter = filter;
+  }
   if (cursor) {
     query.cursor = cursor;
   }
@@ -195,8 +209,7 @@ export type GetTracesResult = {
  * const slowFailures = await getTraces({
  *   client,
  *   project: { projectName: "my-project" },
- *   error: true,
- *   minLatencyMs: 1000,
+ *   filter: "error_count > 0 and latency_ms >= 1000",
  * });
  * ```
  */
@@ -209,6 +222,12 @@ export async function getTraces({
   const client = _client ?? createClient();
   validateLatencyBounds({ minLatencyMs, maxLatencyMs });
   await ensureServerCapability({ client, requirement: LIST_PROJECT_TRACES });
+  if (params.filter) {
+    await ensureServerCapability({
+      client,
+      requirement: GET_TRACES_FILTER_EXPRESSION,
+    });
+  }
   if (errorFilter != null || minLatencyMs != null || maxLatencyMs != null) {
     await ensureServerCapability({ client, requirement: GET_TRACES_FILTERS });
   }