\n\nThis package provides a TypeScript client for the [Arize Phoenix](https://github.com/Arize-ai/phoenix) API. It is still under active development and is subject to change.\n\n## Installation\n\n```bash\n# or yarn, pnpm, bun, etc...\nnpm install @arizeai/phoenix-client\n```\n\n## Configuration\n\nThe client will automatically read environment variables from your environment, if available.\n\nThe following environment variables are used:\n\n- `PHOENIX_ENDPOINT` - The base URL of your Phoenix. This is the canonical setting for the client.\n- `PHOENIX_API_KEY` - The API key to use for authentication.\n- `PHOENIX_CLIENT_HEADERS` - Custom headers to add to all requests. A JSON stringified object.\n- `PHOENIX_COLLECTOR_ENDPOINT` - Read by the OTel SDK for trace export, usually the same URL as `PHOENIX_ENDPOINT`. The client uses it for API access when `PHOENIX_ENDPOINT` is unset.\n\n```bash\nPHOENIX_ENDPOINT='http://localhost:12345' PHOENIX_API_KEY='xxxxxx' pnpx tsx examples/list_datasets.ts\n# emits the following request:\n# GET http://localhost:12345/v1/datasets\n# headers: {\n# \"Authorization\": \"Bearer xxxxxx\",\n# }\n```\n\nAlternatively, you can pass configuration options to the client directly, and they will be prioritized over environment variables and default values.\n\n```ts\nconst phoenix = createClient({\n options: {\n baseUrl: \"http://localhost:6006\",\n headers: {\n Authorization: \"Bearer xxxxxx\",\n },\n },\n});\n```\n\nFor credentials that can expire, create an authenticated fetch implementation\nand pass it to the client. The token provider controls storage and refresh-token\nrotation. Requests that receive a `401` share one refresh operation and are\nretried once.\n\n```ts\nimport { createAuthFetch, createClient } from \"@arizeai/phoenix-client\";\n\nconst authFetch = createAuthFetch({\n getAccessToken: async ({ forceRefresh }) => {\n if (forceRefresh) {\n await refreshAndPersistTokens();\n }\n return loadTokens().accessToken;\n },\n});\n\nconst phoenix = createClient({\n options: {\n baseUrl: \"http://localhost:6006\",\n fetch: authFetch,\n },\n});\n```\n\n## Prompts\n\n`@arizeai/phoenix-client` provides a `prompts` export that exposes utilities for working with prompts for LLMs.\n\n### Creating a Prompt and push it to Phoenix\n\nThe `createPrompt` function can be used to create a prompt in Phoenix for version control and reuse.\n\n```ts\nimport { createPrompt, promptVersion } from \"@arizeai/phoenix-client/prompts\";\n\nconst version = createPrompt({\n name: \"my-prompt\",\n description: \"test-description\",\n version: promptVersion({\n description: \"version description here\",\n modelProvider: \"OPENAI\",\n modelName: \"gpt-3.5-turbo\",\n template: [\n {\n role: \"user\",\n content: \"{{ question }}\",\n },\n ],\n invocationParameters: {\n temperature: 0.8,\n },\n }),\n});\n```\n\nPrompts that are pushed to Phoenix are versioned and can be tagged.\n\n### Pulling a Prompt from Phoenix\n\nThe `getPrompt` function can be used to pull a prompt from Phoenix based on some Prompt Identifier and returns it in the Phoenix SDK Prompt type.\n\n```ts\nimport { getPrompt } from \"@arizeai/phoenix-client/prompts\";\n\nconst prompt = await getPrompt({ name: \"my-prompt\" });\n// ^ you now have a strongly-typed prompt object, in the Phoenix SDK Prompt type\n\nconst promptByTag = await getPrompt({ tag: \"production\", name: \"my-prompt\" });\n// ^ you can optionally specify a tag to filter by\n\nconst promptByVersionId = await getPrompt({\n versionId: \"1234567890\",\n});\n// ^ you can optionally specify a prompt version Id to filter by\n```\n\n### Using a Phoenix Prompt with an LLM Provider SDK\n\nThe `toSDK` helper function can be used to convert a Phoenix Prompt to the format expected by an LLM provider SDK. You can then use the LLM provider SDK as normal, with your prompt.\n\nIf your Prompt is saved in Phoenix as `openai`, you can use the `toSDK` function to convert the prompt to the format expected by OpenAI, or even Anthropic and Vercel AI SDK. We will do a best\neffort conversion to your LLM provider SDK of choice.\n\nThe following LLM provider SDKs are supported:\n\n- Vercel AI SDK: `ai` [ai](https://www.npmjs.com/package/ai)\n- OpenAI: `openai` [openai](https://www.npmjs.com/package/openai) (v6 and v7)\n- Anthropic: `anthropic` [@anthropic-ai/sdk](https://www.npmjs.com/package/@anthropic-ai/sdk)\n\n> **Note:** These provider SDKs are optional peer dependencies — installing `@arizeai/phoenix-client` does not pull them in. Install the one you convert to yourself, e.g. `npm install ai`, `npm install openai`, or `npm install @anthropic-ai/sdk`. Calling `toSDK({ sdk: \"ai\" | \"openai\" | \"anthropic\" })` without the matching SDK installed fails at runtime.\n\n```ts\nimport { generateText } from \"ai\";\nimport { openai } from \"@ai-sdk/openai\";\nimport { getPrompt, toSDK } from \"@arizeai/phoenix-client/prompts\";\n\nconst prompt = await getPrompt({ name: \"my-prompt\" });\nconst promptAsAI = toSDK({\n sdk: \"ai\",\n // ^ the SDK you want to convert the prompt to, supported SDKs are listed above\n variables: {\n \"my-variable\": \"my-value\",\n },\n // ^ you can format the prompt with variables, if the prompt has any variables in its template\n // the format (Mustache, F-string, etc.) is specified in the Prompt itself\n prompt,\n});\n// ^ promptAsAI is now in the format expected by the Vercel AI SDK generateText function\n\nconst response = await generateText({\n model: openai(prompt.model_name),\n // ^ the model adapter provided by the Vercel AI SDK can be swapped out for any other model\n // adapter supported by the Vercel AI SDK. Take care to use the correct model name for the\n // LLM provider you are using.\n ...promptAsAI,\n});\n```\n\n## REST Endpoints\n\nThe client provides a REST API for all endpoints defined in the [Phoenix OpenAPI spec](https://github.com/Arize-ai/phoenix/blob/main/schemas/openapi.json).\n\nEndpoints are accessible via strongly-typed string literals and TypeScript auto-completion inside of the client object.\n\n```ts\nimport { createClient } from \"@arizeai/phoenix-client\";\n\nconst phoenix = createClient();\n\n// Get all datasets\nconst datasets = await phoenix.GET(\"/v1/datasets\");\n\n// Get specific prompt\nconst prompt = await phoenix.GET(\"/v1/prompts/{prompt_identifier}/latest\", {\n params: {\n path: {\n prompt_identifier: \"my-prompt\",\n },\n },\n});\n```\n\nA comprehensive overview of the available endpoints and their parameters is available in the OpenAPI viewer within Phoenix, or in the [Phoenix OpenAPI spec](https://github.com/Arize-ai/phoenix/blob/main/schemas/openapi.json).\n\n## Datasets\n\nThe `@arizeai/phoenix-client` package allows you to create and manage datasets, which are collections of examples used for experiments and evaluation.\n\n### Creating a Dataset\n\nYou can create a dataset by providing a name, description, and an array of examples (each with `input`, `output`, and optional `metadata`).\n\n```ts\nimport { createDataset } from \"@arizeai/phoenix-client/datasets\";\n\nconst { datasetId } = await createDataset({\n name: \"questions\",\n description: \"a simple dataset of questions\",\n examples: [\n {\n input: { question: \"What is the capital of France\" },\n output: { answer: \"Paris\" },\n metadata: {},\n },\n {\n input: { question: \"What is the capital of the USA\" },\n output: { answer: \"Washington D.C.\" },\n metadata: {},\n },\n ],\n});\n// You can now use datasetId to run experiments or add more examples\n```\n\n## Experiments\n\nThe `@arizeai/phoenix-client` package provides an experiments API for running and evaluating tasks on datasets. This is useful for benchmarking models, evaluating outputs, and tracking experiment results in Phoenix.\n\n### Running an Experiment\n\nTo run an experiment, you typically:\n\n1. Create a dataset (or use an existing one)\n2. Define a task function to run on each example\n3. Define one or more evaluators to score or label the outputs\n4. Run the experiment and inspect the results\n\nBelow is a complete example:\n\n```ts\nimport { createDataset } from \"@arizeai/phoenix-client/datasets\";\nimport {\n asExperimentEvaluator,\n runExperiment,\n} from \"@arizeai/phoenix-client/experiments\";\n\n// 1. Create a dataset\nconst { datasetId } = await createDataset({\n name: \"names-dataset\",\n description: \"a simple dataset of names\",\n examples: [\n {\n input: { name: \"John\" },\n output: { text: \"Hello, John!\" },\n metadata: {},\n },\n {\n input: { name: \"Jane\" },\n output: { text: \"Hello, Jane!\" },\n metadata: {},\n },\n ],\n});\n\n// 2. Define a task to run on each example\nconst task = async (example) => `hello ${example.input.name}`;\n\n// 3. Define evaluators\nconst evaluators = [\n asExperimentEvaluator({\n name: \"matches\",\n kind: \"CODE\",\n evaluate: async ({ output, expected }) => {\n const matches = output === expected?.text;\n return {\n label: matches ? \"matches\" : \"does not match\",\n score: matches ? 1 : 0,\n explanation: matches\n ? \"output matches expected\"\n : \"output does not match expected\",\n metadata: {},\n };\n },\n }),\n asExperimentEvaluator({\n name: \"contains-hello\",\n kind: \"CODE\",\n evaluate: async ({ output }) => {\n const matches = typeof output === \"string\" && output.includes(\"hello\");\n return {\n label: matches ? \"contains hello\" : \"does not contain hello\",\n score: matches ? 1 : 0,\n explanation: matches\n ? \"output contains hello\"\n : \"output does not contain hello\",\n metadata: {},\n };\n },\n }),\n];\n\n// 4. Run the experiment\nconst experiment = await runExperiment({\n dataset: { datasetId },\n task,\n evaluators,\n});\n```\n\n> **Hint:** Tasks and evaluators are instrumented using [OpenTelemetry](https://opentelemetry.io/). You can view detailed traces of experiment runs and evaluations directly in the Phoenix UI for debugging and performance analysis.\n\n## Eval Tests\n\nThe package also exposes Vitest and Jest submodules for writing\ndataset-backed evaluations as normal test suites.\n\n```bash\nnpm install -D @arizeai/phoenix-client vitest dotenv\n```\n\n```ts\nimport * as px from \"@arizeai/phoenix-client/vitest\";\nimport { expect } from \"vitest\";\n\npx.describe(\n \"text-to-sql\",\n () => {\n px.test(\n \"select all\",\n {\n input: { userQuery: \"Get all users\" },\n expected: { sql: \"SELECT * FROM users;\" },\n },\n async ({ input, expected }) => {\n const sql = await generateSql(input.userQuery);\n px.logOutput({ sql });\n expect(sql).toEqual(expected?.sql);\n }\n );\n },\n {\n acceptanceCriteria: [\n // every test must pass (100% of the auto-logged `pass` boolean is true)\n {\n annotationName: \"pass\",\n metric: \"passRate\",\n passFn: (a) => a.score === true,\n minPassRate: 1,\n },\n ],\n }\n);\n```\n\nThe reference output can be supplied under any one of three interchangeable\nkeys — `expected`, `reference`, or `output` — so you can match whichever name\nyour evaluators expect. They all resolve to the same slot: the dataset\nexample's `output`, exposed to evaluators and the test body as `expected`.\nSupplying more than one at a time is a type error.\n\nUse `@arizeai/phoenix-client/vitest/reporter` or\n`@arizeai/phoenix-client/jest/reporter` to print Phoenix dataset and\nexperiment links, annotation aggregates, and acceptance criteria at the end\nof a run. Acceptance criteria gate the suite after it finishes — `average`\nchecks an aggregate bar (so CI can allow a mean of 80% while still running\nevery case), and `passRate` requires a minimum fraction of runs to satisfy a\nper-run `passFn` predicate.\n\nSee the [CI Eval Tests](https://arize.com/docs/phoenix/sdk-api-reference/typescript/packages/phoenix-client/ci-evals),\n[Vitest](https://arize.com/docs/phoenix/sdk-api-reference/typescript/packages/phoenix-client/ci-evals-vitest),\n[Jest](https://arize.com/docs/phoenix/sdk-api-reference/typescript/packages/phoenix-client/ci-evals-jest),\nand [Annotations](https://arize.com/docs/phoenix/sdk-api-reference/typescript/packages/phoenix-client/ci-evals-annotations)\nguides for setup, the full\n`describe` / `test` / `test.each` API, acceptance criteria, repetitions,\ndry-run mode, and annotation details.\n\n## Traces\n\nThe `@arizeai/phoenix-client` package provides a `traces` export for retrieving trace data from Phoenix projects.\n\n### Fetching Traces\n\nUse `getTraces` to retrieve traces with optional filtering, sorting, and pagination.\n\n```ts\nimport { getTraces } from \"@arizeai/phoenix-client/traces\";\n\n// Get the latest 10 traces\nconst result = await getTraces({\n project: { projectName: \"my-project\" },\n limit: 10,\n});\nconsole.log(result.data); // array of trace objects\n\n// Filter by time range and include full span details\nconst detailed = await getTraces({\n project: { projectName: \"my-project\" },\n startTime: \"2026-03-01T00:00:00Z\",\n endTime: new Date(),\n includeSpans: true,\n sort: \"latency_ms\",\n order: \"desc\",\n});\n\n// Filter by session\nconst sessionTraces = await getTraces({\n project: { projectName: \"my-project\" },\n sessionId: \"my-session-id\",\n});\n\n// Filter by error status and latency (requires Phoenix server >= 20.12.0)\nconst slowFailures = await getTraces({\n project: { projectName: \"my-project\" },\n filter: \"error_count > 0 and latency_ms >= 1000\",\n});\n```\n\n| Parameter | Type | Description |\n| -------------- | ------------------------------ | ------------------------------------------------------------ |\n| `project` | `ProjectIdentifier` | The project (by name or ID) — **required** |\n| `startTime` | `Date \\| string \\| null` | Inclusive lower bound on trace start time |\n| `endTime` | `Date \\| string \\| null` | Exclusive upper bound on trace start time |\n| `sort` | `\"start_time\" \\| \"latency_ms\"` | Sort field |\n| `order` | `\"asc\" \\| \"desc\"` | Sort direction |\n| `limit` | `number` | Maximum number of traces to return |\n| `cursor` | `string \\| null` | Pagination cursor |\n| `includeSpans` | `boolean` | Include full span details for each trace |\n| `sessionId` | `string \\| string[] \\| null` | Filter traces by session identifier(s) |\n| `filter` | `string \\| null` | Trace filter expression |\n| `error` | `boolean \\| null` | Only traces with (`true`) or without (`false`) errored spans |\n| `minLatencyMs` | `number \\| null` | Inclusive lower bound on trace latency (ms) |\n| `maxLatencyMs` | `number \\| null` | Inclusive upper bound on trace latency (ms) |\n\n`error`, `minLatencyMs`, and `maxLatencyMs` are deprecated but remain supported on\nserver >= 20.8.0. Use `error_count > 0` / `error_count == 0`, `latency_ms >= N`, and\n`latency_ms <= N` in `filter` instead. Empty expressions do not filter; invalid\nexpressions return HTTP 400. Keep the same expression when requesting the next page.\n\n### Pagination\n\nUse the `cursor` from a previous result to fetch the next page:\n\n```ts\nimport { getTraces } from \"@arizeai/phoenix-client/traces\";\n\nlet cursor: string | null = null;\nconst allTraces = [];\n\ndo {\n const result = await getTraces({\n project: { projectName: \"my-project\" },\n limit: 50,\n cursor,\n });\n allTraces.push(...result.data);\n cursor = result.nextCursor ?? null;\n} while (cursor);\n```\n\n> **Note:** Requires Phoenix server >= 13.15.0.\n\n### Trace Annotations\n\nAdd structured feedback (label/score by name) to entire traces. Use `addTraceAnnotation` for one trace or `logTraceAnnotations` for batches.\n\n```ts\nimport {\n addTraceAnnotation,\n logTraceAnnotations,\n} from \"@arizeai/phoenix-client/traces\";\n\n// Single annotation\nconst result = await addTraceAnnotation({\n traceAnnotation: {\n traceId: \"abc123\",\n name: \"correctness\",\n label: \"correct\",\n score: 1.0,\n annotatorKind: \"HUMAN\",\n },\n sync: true, // returns { id: \"...\" } when sync, null when async\n});\n\n// Batch\nawait logTraceAnnotations({\n traceAnnotations: [\n {\n traceId: \"abc123\",\n name: \"correctness\",\n label: \"correct\",\n score: 1.0,\n annotatorKind: \"HUMAN\",\n },\n {\n traceId: \"def456\",\n name: \"faithfulness\",\n label: \"faithful\",\n score: 0.9,\n annotatorKind: \"LLM\",\n },\n ],\n sync: true,\n});\n```\n\nThe reserved name `note` is rejected — use `addTraceNote` instead for free-form notes (see below).\n\n### Trace Notes\n\nNotes are a special type of annotation for free-form text — useful for open coding, where reviewers leave qualitative observations on a trace before any rubric exists. Multiple notes can coexist on the same trace.\n\n```ts\nimport { addTraceNote } from \"@arizeai/phoenix-client/traces\";\n\nawait addTraceNote({\n traceNote: {\n traceId: \"abc123\",\n note: \"Needs follow-up — unexpected tool call sequence\",\n },\n});\n```\n\n> **Note:** `addTraceNote` requires Phoenix server >= 14.13.0.\n\n## Spans\n\nThe `@arizeai/phoenix-client` package provides a `spans` export for querying spans with powerful filtering.\n\n### Fetching Spans\n\nUse `getSpans` to retrieve spans with filtering by kind, status, name, trace, and more.\n\n```ts\nimport { getSpans } from \"@arizeai/phoenix-client/spans\";\n\n// Get recent spans\nconst result = await getSpans({\n project: { projectName: \"my-project\" },\n limit: 100,\n});\n\n// Filter by span kind and status\nconst errorLLMSpans = await getSpans({\n project: { projectName: \"my-project\" },\n spanKind: \"LLM\",\n statusCode: \"ERROR\",\n});\n\n// Filter by name and trace\nconst spans = await getSpans({\n project: { projectName: \"my-project\" },\n name: \"chat_completion\",\n traceIds: [\"trace-abc\", \"trace-def\"],\n});\n\n// Root spans only\nconst rootSpans = await getSpans({\n project: { projectName: \"my-project\" },\n parentId: null,\n});\n```\n\n| Parameter | Type | Description |\n| ------------ | ------------------------------------ | --------------------------------------------------------------- |\n| `project` | `ProjectIdentifier` | The project (by name or ID) — **required** |\n| `startTime` | `Date \\| string \\| null` | Inclusive lower bound time |\n| `endTime` | `Date \\| string \\| null` | Exclusive upper bound time |\n| `limit` | `number` | Maximum number of spans to return |\n| `cursor` | `string \\| null` | Pagination cursor (Span GlobalID) |\n| `traceIds` | `string[] \\| null` | Filter by trace ID(s) |\n| `parentId` | `string \\| null` | Filter by parent span ID (`null` for root spans only) |\n| `name` | `string \\| string[] \\| null` | Filter by span name(s) |\n| `spanKind` | `SpanKindFilter \\| SpanKindFilter[]` | Filter by span kind (`LLM`, `CHAIN`, `TOOL`, `RETRIEVER`, etc.) |\n| `statusCode` | `SpanStatusCode \\| SpanStatusCode[]` | Filter by status code (`OK`, `ERROR`, `UNSET`) |\n\n### Logging Spans\n\nUse `logSpans` to submit spans directly to a project using Phoenix's simplified span structure — the same shape returned by `getSpans`. This is useful for backfilling or migrating spans without going through OpenTelemetry. If your application is already instrumented with OpenTelemetry, export spans via `@arizeai/phoenix-otel` instead.\n\n```ts\nimport { logSpans } from \"@arizeai/phoenix-client/spans\";\n\nconst result = await logSpans({\n project: { projectName: \"my-project\" },\n spans: [\n {\n name: \"chat_completion\",\n context: { trace_id: \"abc123\", span_id: \"def456\" },\n span_kind: \"LLM\",\n start_time: \"2024-01-01T00:00:00Z\",\n end_time: \"2024-01-01T00:00:01Z\",\n status_code: \"OK\",\n attributes: { \"llm.model_name\": \"gpt-4\" },\n },\n ],\n});\nconsole.log(`Queued ${result.totalQueued} of ${result.totalReceived} spans`);\n```\n\nIf any span in the request is invalid or a duplicate of a span that already exists, none of the spans are queued and `logSpans` throws a `SpanCreationError` with `invalidSpans` and `duplicateSpans` details.\n\n## Span Annotations\n\nThe `spans` export also provides functions for managing span annotations — adding evaluations, feedback, and labels to spans.\n\n### Adding a Single Annotation\n\n```ts\nimport { addSpanAnnotation } from \"@arizeai/phoenix-client/spans\";\n\nconst result = await addSpanAnnotation({\n spanAnnotation: {\n spanId: \"f8b1c3a2d4e5f678\",\n name: \"correctness\",\n label: \"correct\",\n score: 1.0,\n explanation: \"The response accurately answered the question\",\n annotatorKind: \"HUMAN\",\n },\n sync: true, // wait for the annotation ID to be returned\n});\n// result: { id: \"annotation-id\" } when sync: true, null when sync: false\n```\n\n### Logging Multiple Annotations\n\n```ts\nimport { logSpanAnnotations } from \"@arizeai/phoenix-client/spans\";\n\nconst results = await logSpanAnnotations({\n spanAnnotations: [\n {\n spanId: \"f8b1c3a2d4e5f678\",\n name: \"relevance\",\n label: \"relevant\",\n score: 0.95,\n annotatorKind: \"LLM\",\n },\n {\n spanId: \"a1b2c3d4e5f67890\",\n name: \"relevance\",\n label: \"irrelevant\",\n score: 0.2,\n annotatorKind: \"LLM\",\n },\n ],\n sync: true,\n});\n// results: [{ id: \"...\" }, { id: \"...\" }]\n```\n\n### Fetching Span Annotations\n\n```ts\nimport { getSpanAnnotations } from \"@arizeai/phoenix-client/spans\";\n\nconst result = await getSpanAnnotations({\n project: { projectName: \"my-project\" },\n spanIds: [\"f8b1c3a2d4e5f678\", \"a1b2c3d4e5f67890\"],\n includeAnnotationNames: [\"relevance\", \"correctness\"],\n limit: 100,\n});\nconsole.log(result.data); // array of span annotation objects\n```\n\n| Parameter | Type | Description |\n| ------------------------ | ------------------- | ------------------------------------------------ |\n| `project` | `ProjectIdentifier` | The project (by name or ID) — **required** |\n| `spanIds` | `string[]` | Span IDs to fetch annotations for — **required** |\n| `includeAnnotationNames` | `string[]` | Only return annotations with these names |\n| `excludeAnnotationNames` | `string[]` | Exclude annotations with these names |\n| `cursor` | `string \\| null` | Pagination cursor |\n| `limit` | `number` | Maximum annotations to return |\n\n## Sessions\n\nThe `@arizeai/phoenix-client` package provides a `sessions` export for managing conversation sessions and their annotations.\n\n### Fetching Sessions\n\nUse `listSessions` to list all sessions for a project, or `getSession` to retrieve a single session by ID.\n\n```ts\nimport {\n listSessions,\n getSession,\n addSessionAnnotation,\n addSessionNote,\n} from \"@arizeai/phoenix-client/sessions\";\n\n// List all sessions for a project\nconst sessions = await listSessions({\n project: \"my-project\",\n});\n\nfor (const session of sessions) {\n console.log(\n `Session: ${session.sessionId}, Traces: ${session.traces.length}`\n );\n}\n\n// Get a single session by its ID\nconst session = await getSession({ sessionId: \"my-session-id\" });\nconsole.log(session.traces); // array of trace summaries in the session\n```\n\n### Adding Session Annotations\n\n```ts\nawait addSessionAnnotation({\n sessionAnnotation: {\n sessionId: \"my-session-id\",\n name: \"user-satisfaction\",\n label: \"satisfied\",\n score: 0.9,\n annotatorKind: \"HUMAN\",\n },\n});\n```\n\n### Adding Session Notes\n\nSession notes require Phoenix server `14.17.0` or newer.\n\n```ts\nawait addSessionNote({\n sessionNote: {\n sessionId: \"my-session-id\",\n note: \"Needs review\",\n },\n});\n```\n\n## Projects\n\nThe `@arizeai/phoenix-client` package provides a `projects` export for listing projects and managing their retention-policy assignments.\n\n### Fetching Projects\n\nUse `getProjects` to list projects. Pagination is handled for you.\n\n```ts\nimport { getProjects } from \"@arizeai/phoenix-client/projects\";\n\n// List every project\nconst projects = await getProjects();\n\nfor (const project of projects) {\n console.log(`Project: ${project.name} (${project.id})`);\n}\n```\n\nPass `nameContains` to filter by a case-insensitive substring of the project name. The filter is applied server-side and requires Phoenix server `17.16.0` or newer.\n\n```ts\nconst agentProjects = await getProjects({ nameContains: \"agent\" });\n```\n\n### Assigning a Retention Policy\n\nUse `setProjectRetentionPolicy` to assign an existing trace retention policy by GlobalID. Select the project by name or GlobalID.\n\n```ts\nimport { setProjectRetentionPolicy } from \"@arizeai/phoenix-client/projects\";\n\nawait setProjectRetentionPolicy({\n projectName: \"support-bot\",\n policyId: \"UHJvamVjdFRyYWNlUmV0ZW50aW9uUG9saWN5OjI=\",\n});\n```\n\nPass `policyId: null` to reset the project to Phoenix's default retention policy:\n\n```ts\nawait setProjectRetentionPolicy({\n projectId: \"UHJvamVjdDox\",\n policyId: null,\n});\n```\n\nThis helper only changes a project's assignment to an existing policy. Creating, reading, updating, and deleting retention policies is outside the scope of the TypeScript projects helper.\n\n## Secrets\n\nUse the `secrets` entrypoint to atomically create, update, or delete encrypted\nprovider credentials. A string value creates or updates a key, while `null`\ndeletes it. Duplicate keys use the last occurrence in the batch. The result\ncontains only changed key names and never returns secret values.\n\n```ts\nimport { upsertOrDeleteSecrets } from \"@arizeai/phoenix-client/secrets\";\n\nconst apiKey = process.env.OPENAI_API_KEY;\nif (!apiKey) throw new Error(\"OPENAI_API_KEY is required\");\n\nconst result = await upsertOrDeleteSecrets({\n secrets: [\n { key: \"OPENAI_API_KEY\", value: apiKey },\n { key: \"OLD_PROVIDER_API_KEY\", value: null },\n ],\n});\n\nconsole.log(result.upsertedKeys);\nconsole.log(result.deletedKeys);\n```\n\nManaging secrets requires an administrator when Phoenix authentication is\nenabled. Avoid logging the request batch or otherwise retaining its values.\n\n## Examples\n\nTo run examples, install dependencies using `pnpm` and run:\n\n```bash\npnpm install\npnpx tsx examples/list_datasets.ts\n# change the file name to run other examples\n```\n\n## Compatibility\n\nThis package utilizes [openapi-ts](https://openapi-ts.pages.dev/) to generate the types from the Phoenix OpenAPI spec.\n\nBecause of this, this package only works with the `arize-phonix` server 8.0.0 and above.\n\nCompatibility Table:\n\n| Phoenix Client Version | Phoenix Server Version |\n| ---------------------- | ---------------------- |\n| ^2.0.0 | ^9.0.0 |\n| ^1.0.0 | ^8.0.0 |\n\n---\n\n## Community\n\nJoin our community to connect with thousands of AI builders:\n\n- 🌍 Join our [Slack community](https://join.slack.com/t/arize-ai/shared_invite/zt-3r07iavnk-ammtATWSlF0pSrd1DsMW7g).\n- 📚 Read the [Phoenix documentation](https://arize.com/docs/phoenix).\n- 💡 Ask questions and provide feedback in the _#phoenix-support_ channel.\n- 🌟 Leave a star on our [GitHub](https://github.com/Arize-ai/phoenix).\n- 🐞 Report bugs with [GitHub Issues](https://github.com/Arize-ai/phoenix/issues).\n- 𝕏 Follow us on [𝕏](https://twitter.com/ArizePhoenix).\n- 💼 Follow us on [LinkedIn](https://www.linkedin.com/showcase/113218220).\n- 🗺️ Check out our [roadmap](https://github.com/orgs/Arize-ai/projects/45) to see where we're heading next.\n","readmeFilename":""}
![\"Arize](\"https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg\")
\n ![\"NPM](\"https://img.shields.io/npm/v/%40arizeai%2Fphoenix-client\")
\n ![\"Documentation\"](\"https://img.shields.io/badge/docs-blue?logo=typescript&logoColor=white\"){kind=icon}
\n ![](\"https://static.scarf.sh/a.png?x-pxid=8e8e8b34-7900-43fa-a38f-1f070bd48c64&page=js/packages/phoenix-client/README.md\")
\n