@arizeai/phoenix-client 7.11.0 → 7.13.0

package/docs/overview.mdx

@@ -3,7 +3,7 @@ title: "Overview"
 description: "Typed TypeScript client for Phoenix platform APIs"
 ---
 
-`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for projects, prompts, datasets, experiments, spans, sessions, traces, users, and CI-friendly dataset-backed eval tests.
+`@arizeai/phoenix-client` is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for projects, prompts, datasets, experiments, spans, sessions, traces, secrets, users, and CI-friendly dataset-backed eval tests.
 
 ## Install
 
@@ -44,6 +44,7 @@ That gives the agent version-matched docs plus the exact implementation and gene
 | `@arizeai/phoenix-client/spans` | Span search, notes, and span/document annotations |
 | `@arizeai/phoenix-client/sessions` | Session listing, retrieval, and session annotations |
 | `@arizeai/phoenix-client/traces` | Project trace retrieval, transfers, and trace annotations |
+| `@arizeai/phoenix-client/secrets` | Atomic secret creation, rotation, and deletion |
 | `@arizeai/phoenix-client/users` | Current authenticated user retrieval |
 | `@arizeai/phoenix-client/vitest` | Vitest entrypoint for dataset-backed eval tests |
 | `@arizeai/phoenix-client/vitest/reporter` | Vitest reporter for Phoenix eval summaries |
@@ -164,6 +165,7 @@ Prefer this layer when:
 - [Annotations](./annotations) — annotation concepts, then [Span](./span-annotations), [Document](./document-annotations), and [Session](./session-annotations) annotations for detailed usage
 - [CI Eval Tests](./ci-evals) — Vitest/Jest eval suites backed by Phoenix datasets and experiments
 - [Spans](./spans), [Sessions](./sessions), [Traces](./traces), [Users](./users) — retrieval and maintenance
+- [Secrets](./secrets) — encrypted provider credential management
 
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
@@ -180,6 +182,7 @@ Prefer this layer when:
     <li><code>src/spans/</code></li>
     <li><code>src/sessions/</code></li>
     <li><code>src/traces/</code></li>
+    <li><code>src/secrets/</code></li>
     <li><code>src/users/</code></li>
     <li><code>src/vitest/</code></li>
     <li><code>src/jest/</code></li>

package/docs/secrets.mdx

@@ -0,0 +1,68 @@
+---
+title: "Secrets"
+description: "Atomically manage encrypted provider credentials with the Phoenix TypeScript client"
+---
+
+Use `upsertOrDeleteSecrets` from the `@arizeai/phoenix-client/secrets` entrypoint to create, rotate, or delete encrypted provider credentials in one atomic request.
+
+<Warning>
+Managing secrets requires an administrator when Phoenix authentication is enabled. Do not log the request batch or retain its values outside your credential store.
+</Warning>
+
+## Create, Update, And Delete Secrets
+
+Each batch entry has a `key` and a required `value`:
+
+- A string value creates or updates the secret.
+- `null` deletes the secret.
+- When a key occurs more than once, its last occurrence wins.
+
+```ts
+import { upsertOrDeleteSecrets } from "@arizeai/phoenix-client/secrets";
+
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) throw new Error("OPENAI_API_KEY is required");
+
+const result = await upsertOrDeleteSecrets({
+  secrets: [
+    { key: "OPENAI_API_KEY", value: apiKey },
+    { key: "OLD_PROVIDER_API_KEY", value: null },
+  ],
+});
+
+console.log(result.upsertedKeys);
+console.log(result.deletedKeys);
+```
+
+The operation returns only `upsertedKeys` and `deletedKeys`. Submitted secret values are never returned or added to helper error messages.
+
+## Use An Explicit Client
+
+Pass `client` when you need to target a particular Phoenix instance. Otherwise, the helper creates a client from the standard Phoenix environment configuration.
+
+```ts
+import { createClient } from "@arizeai/phoenix-client";
+import { upsertOrDeleteSecrets } from "@arizeai/phoenix-client/secrets";
+
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) throw new Error("OPENAI_API_KEY is required");
+
+const client = createClient({
+  options: { baseUrl: "https://phoenix.example.com" },
+});
+
+await upsertOrDeleteSecrets({
+  client,
+  secrets: [{ key: "OPENAI_API_KEY", value: apiKey }],
+});
+```
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/secrets/index.ts</code></li>
+    <li><code>src/secrets/upsertOrDeleteSecrets.ts</code></li>
+    <li><code>src/client.ts</code></li>
+    <li><code>src/__generated__/api/v1.ts</code></li>
+  </ul>
+</section>

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.11.0",
+  "version": "7.13.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -53,6 +53,10 @@
       "import": "./dist/esm/sessions/index.js",
       "require": "./dist/src/sessions/index.js"
     },
+    "./secrets": {
+      "import": "./dist/esm/secrets/index.js",
+      "require": "./dist/src/secrets/index.js"
+    },
     "./projects": {
       "import": "./dist/esm/projects/index.js",
       "require": "./dist/src/projects/index.js"
@@ -103,31 +107,31 @@
     }
   },
   "dependencies": {
-    "@arizeai/openinference-semantic-conventions": "^2.9.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.5.4"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^4.0.60",
-    "@ai-sdk/otel": "^1.0.93",
+    "@ai-sdk/openai": "^4.0.71",
+    "@ai-sdk/otel": "^1.0.107",
     "@anthropic-ai/sdk": "^0.111.0",
-    "@arizeai/phoenix-evals": "2.5.0",
+    "@arizeai/phoenix-evals": "2.6.0",
     "@arizeai/phoenix-testing": "0.0.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
-    "@types/async": "^3.2.25",
-    "@types/node": "^26.4.1",
-    "ai": "^7.0.93",
+    "@types/async": "^3.2.26",
+    "@types/node": "^26.6.2",
+    "ai": "^7.0.107",
     "dotenv": "^17.4.2",
-    "jest": "^30.5.1",
+    "jest": "^30.5.2",
     "openai": "^6.49.0",
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.23.13",
-    "vitest": "^5.0.0"
+    "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 */
@@ -8959,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;
@@ -10112,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: {
@@ -10137,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: {
@@ -11904,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: {
@@ -11923,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/secrets/index.ts

@@ -0,0 +1 @@
+export * from "./upsertOrDeleteSecrets";

package/src/secrets/upsertOrDeleteSecrets.ts

@@ -0,0 +1,87 @@
+import { createClient } from "../client";
+import type { ClientFn } from "../types/core";
+
+/**
+ * A secret to create, update, or delete.
+ */
+export interface SecretInput {
+  /** The environment-style key used to identify the secret. */
+  key: string;
+  /** A value to create or update, or `null` to delete the key. */
+  value: string | null;
+}
+
+/**
+ * Parameters for atomically updating secrets.
+ */
+export interface UpsertOrDeleteSecretsParams extends ClientFn {
+  /**
+   * Ordered secret updates. When a key occurs more than once, the server
+   * applies only its last occurrence.
+   */
+  secrets: SecretInput[];
+}
+
+/**
+ * The names of the keys changed by a secrets update.
+ *
+ * Secret values are intentionally excluded.
+ */
+export interface UpsertOrDeleteSecretsResult {
+  /** Keys that were created or updated. */
+  upsertedKeys: string[];
+  /** Keys that were deleted. */
+  deletedKeys: string[];
+}
+
+/**
+ * Atomically create, update, or delete a batch of Phoenix secrets.
+ *
+ * A non-null value creates or updates a secret, while `null` deletes it.
+ * Duplicate keys use the last occurrence in the batch. The result contains
+ * key names only; submitted values are never returned or logged.
+ *
+ * @param params - The secrets update.
+ * @param params.client - Optional Phoenix client instance.
+ * @param params.secrets - Ordered key/value-or-null updates.
+ * @returns The names of the keys that were upserted and deleted.
+ *
+ * @example
+ * ```ts
+ * import { upsertOrDeleteSecrets } from "@arizeai/phoenix-client/secrets";
+ *
+ * const apiKey = process.env.OPENAI_API_KEY;
+ * if (!apiKey) throw new Error("OPENAI_API_KEY is required");
+ *
+ * const result = await upsertOrDeleteSecrets({
+ *   secrets: [
+ *     { key: "OPENAI_API_KEY", value: apiKey },
+ *     { key: "OLD_PROVIDER_API_KEY", value: null },
+ *   ],
+ * });
+ * ```
+ */
+export async function upsertOrDeleteSecrets({
+  client: _client,
+  secrets,
+}: UpsertOrDeleteSecretsParams): Promise<UpsertOrDeleteSecretsResult> {
+  const client = _client ?? createClient();
+  const { data, error } = await client.PUT("/v1/secrets", {
+    body: { secrets },
+  });
+
+  // Do not include the server error payload here: validation responses can be
+  // influenced by submitted data, which must never enter helper error text.
+  if (error) {
+    throw new Error("Failed to upsert or delete secrets");
+  }
+
+  if (!data?.data) {
+    throw new Error("Failed to upsert or delete secrets: no data returned");
+  }
+
+  return {
+    upsertedKeys: data.data.upserted_keys,
+    deletedKeys: data.data.deleted_keys,
+  };
+}

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 });
   }