Overview

@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#

npm install @arizeai/phoenix-client

Minimal Example#

import { createClient } from "@arizeai/phoenix-client";import { listDatasets } from "@arizeai/phoenix-client/datasets";const client = createClient();const datasets = await listDatasets({ client });

Docs And Source In node_modules#

After install, a coding agent can inspect the installed package directly:

node_modules/@arizeai/phoenix-client/docs/node_modules/@arizeai/phoenix-client/src/

That gives the agent version-matched docs plus the exact implementation and generated API types that shipped with your project.

Module Map#

Configuration#

createClient() resolves Phoenix client options in this order: library defaults, environment variables, then explicit options. In most applications, the normal setup is to set PHOENIX_ENDPOINT and PHOENIX_API_KEY in the environment and call createClient() with no overrides.

Recommended Setup#

Use the environment-driven path unless you have a specific reason to override client options in code.

export PHOENIX_ENDPOINT=http://localhost:6006export PHOENIX_API_KEY=<your-api-key>

For a remote deployment, PHOENIX_ENDPOINT is that instance’s base URL, e.g. https://your-phoenix.example.com.

import { createClient } from "@arizeai/phoenix-client";const client = createClient();const datasets = await client.GET("/v1/datasets");

PHOENIX_API_KEY is converted into Authorization: Bearer <key> automatically. You do not need to build that header yourself unless you are explicitly overriding headers.

Explicit Overrides#

import { createClient } from "@arizeai/phoenix-client";const client = createClient({  options: {    baseUrl: "https://phoenix.example.com",    headers: {      Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,    },  },});

Use explicit options when you want configuration to live in code or when you need to override the environment for a specific client instance.

createClient Parameters#

Resolved Phoenix Options#

These are the Phoenix-specific options this package resolves before creating the underlying OpenAPI client:

Header Override Rule#

If you pass options.headers, they replace the environment-derived header object rather than deep-merging with it. That means if you override headers and still want API key authentication, include Authorization yourself:

const client = createClient({  options: {    headers: {      Authorization: `Bearer ${process.env.PHOENIX_API_KEY}`,    },  },});

Environment Variables#

API Client#

createClient() returns an openapi-fetch client that is typed against Phoenix’s generated OpenAPI schema. Use this layer when you need an endpoint that does not yet have a high-level helper.

import { createClient } from "@arizeai/phoenix-client";const client = createClient();const datasets = await client.GET("/v1/datasets");const prompt = await client.GET("/v1/prompts/{prompt_identifier}/latest", {  params: {    path: {      prompt_identifier: "support-response",    },  },});

The root export exposes generated API types: pathsV1, componentsV1, operationsV1, Types, and PhoenixClient.

Prefer this layer when:

• you need a newly added endpoint before a helper exists
• you want direct control over route, body, and query params
• you are building thin wrappers around Phoenix routes in your own codebase

Where To Start#

• Projects, Prompts, Datasets, Experiments — higher-level workflows
• Annotations — annotation concepts, then Span, Document, and Session annotations for detailed usage
• CI Eval Tests — Vitest/Jest eval suites backed by Phoenix datasets and experiments
• Spans, Sessions, Traces, Users — retrieval and maintenance
• Secrets — encrypted provider credential management