Skip to main content
@arizeai/phoenix-client is the typed TypeScript client for Phoenix platform APIs. It ships a small root REST client plus focused module entrypoints for prompts, datasets, experiments, spans, sessions, and traces.

​
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

ImportPurpose
@arizeai/phoenix-clientcreateClient, generated OpenAPI types, config helpers
@arizeai/phoenix-client/promptsPrompt CRUD plus toSDK conversion
@arizeai/phoenix-client/datasetsDataset creation and retrieval
@arizeai/phoenix-client/experimentsExperiment execution and lifecycle
@arizeai/phoenix-client/spansSpan search, notes, and span/document annotations
@arizeai/phoenix-client/sessionsSession listing, retrieval, and session annotations
@arizeai/phoenix-client/tracesProject trace retrieval

​
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_HOST and PHOENIX_API_KEY in the environment and call createClient() with no overrides. Use the environment-driven path unless you have a specific reason to override client options in code. 
export PHOENIX_HOST=http://localhost:6006
export PHOENIX_API_KEY=<your-api-key>
If you’re using Phoenix Cloud, PHOENIX_HOST may look like https://app.phoenix.arize.com/s/my-space. 
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

FieldTypeDescription
optionsPartial<ClientOptions>Explicit options passed to the underlying openapi-fetch client.
getEnvironmentOptions() => Partial<ClientOptions>Optional resolver for environment-derived options. The default implementation reads process.env when available.

​
Resolved Phoenix Options

These are the Phoenix-specific options this package resolves before creating the underlying OpenAPI client:
OptionTypeDescription
baseUrlstringBase Phoenix URL. Defaults to http://localhost:6006, or PHOENIX_HOST when that environment variable is set.
headersClientOptions["headers"]Headers sent on every request. PHOENIX_API_KEY populates Authorization automatically. Explicit headers replace environment-derived headers.

​
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

VariableMaps toDescription
PHOENIX_HOSToptions.baseUrlBase Phoenix URL, for example http://localhost:6006.
PHOENIX_API_KEYoptions.headers.AuthorizationBearer token for authenticated environments.
PHOENIX_CLIENT_HEADERSoptions.headersOptional JSON-encoded object of additional headers to send on every request. Most setups do not need this.

​
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

​
Source Map

  • src/client.ts
  • src/config.ts
  • src/generated/api/v1.ts
  • src/types/core.ts
  • src/prompts/
  • src/datasets/
  • src/experiments/
  • src/spans/
  • src/sessions/
  • src/traces/
  • src/types/