Implementation:Arize ai Phoenix Client Constructor

Knowledge Sources	Phoenix
Domains	AI Observability, API Client, Authentication
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for constructing and configuring synchronous and asynchronous API clients provided by the arize-phoenix-client package.

Description

The Client and AsyncClient classes are the primary entry points for interacting with a Phoenix server. On construction, each client resolves the server URL (from an explicit argument, environment variables, or the default http://localhost:6006), merges authentication and custom headers through the internal _update_headers() function, and creates an httpx.Client (or httpx.AsyncClient) transport. The client then composes resource-specific sub-clients as properties: .prompts, .projects, .spans, .traces, .sessions, .annotations (deprecated), .datasets, and .experiments. All sub-clients share the same underlying HTTP connection.

If a pre-configured httpx.Client or httpx.AsyncClient is passed via the http_client parameter, the base_url, api_key, and headers arguments are ignored and the provided client is used directly.

Usage

Use the Client constructor when:

Starting any synchronous script or pipeline that needs to interact with Phoenix (annotation workflows, data exports, experiment runs).
Connecting to a remote Phoenix instance that requires API key authentication.
Injecting a custom httpx.Client with specific timeout, proxy, or retry configurations.

Use the AsyncClient constructor when:

Working inside an async application (e.g., FastAPI route handlers, async batch processors).
Running concurrent annotation or querying tasks with asyncio.

Code Reference

Source Location

Repository: Phoenix
File: packages/phoenix-client/src/phoenix/client/client.py
Lines: 18-139 (Client), 142-262 (AsyncClient), 265-278 (_update_headers)

Signature

class Client:
    def __init__(
        self,
        *,
        base_url: str | httpx.URL | None = None,
        api_key: str | None = None,
        headers: Mapping[str, str] | None = None,
        http_client: httpx.Client | None = None,
    ):
        ...

class AsyncClient:
    def __init__(
        self,
        *,
        base_url: str | httpx.URL | None = None,
        api_key: str | None = None,
        headers: Mapping[str, str] | None = None,
        http_client: httpx.AsyncClient | None = None,
    ):
        ...

Import

from phoenix.client import Client
from phoenix.client import AsyncClient

I/O Contract

Inputs

Name	Type	Required	Description
base_url	httpx.URL \| None	No	The base URL for the Phoenix API endpoint. If not provided, resolved from the `PHOENIX_COLLECTOR_ENDPOINT` or `PHOENIX_HOST_ROOT` environment variables, falling back to `http://localhost:6006`. Ignored when `http_client` is provided.
api_key	None	No	API key for authentication. When provided, it is attached as `Authorization: Bearer {api_key}` in all requests. This overrides any existing Authorization header.
headers	None	No	Additional HTTP headers to include in every request. User-specified headers take precedence over environment-derived headers. Ignored when `http_client` is provided.
http_client	httpx.AsyncClient \| None	No	A pre-configured httpx client instance. When provided, all other constructor parameters (`base_url`, `api_key`, `headers`) are ignored and the client is used as-is.

Outputs

Name	Type	Description
(instance)	`Client` or `AsyncClient`	A configured client instance with the following resource sub-client properties:
.prompts	`Prompts` / `AsyncPrompts`	Sub-client for prompt management operations.
.projects	`Projects` / `AsyncProjects`	Sub-client for project management operations.
.spans	`Spans` / `AsyncSpans`	Sub-client for span retrieval, logging, annotation, and deletion.
.traces	`Traces` / `AsyncTraces`	Sub-client for trace-related operations.
.sessions	`Sessions` / `AsyncSessions`	Sub-client for session management.
.annotations	`Annotations` / `AsyncAnnotations`	Deprecated. Legacy sub-client that delegates to `.spans`.
.datasets	`Datasets` / `AsyncDatasets`	Sub-client for dataset management operations.
.experiments	`Experiments` / `AsyncExperiments`	Sub-client for experiment management operations.

Usage Examples

Default Local Connection

from phoenix.client import Client

# Connects to http://localhost:6006 with no authentication
client = Client()
spans = client.spans.get_spans(project_identifier="my-project")

Remote Authenticated Connection

from phoenix.client import Client

client = Client(
    base_url="https://phoenix.example.com",
    api_key="phx_sk_abc123...",
)
annotations = client.spans.get_span_annotations(
    span_ids=["span1", "span2"],
    project_identifier="production",
)

Async Client Usage

import asyncio
from phoenix.client import AsyncClient

async def main():
    client = AsyncClient(
        base_url="https://phoenix.example.com",
        api_key="phx_sk_abc123...",
    )
    spans = await client.spans.get_spans(project_identifier="my-project")
    print(f"Retrieved {len(spans)} spans")

asyncio.run(main())

Custom HTTP Client with Timeouts

import httpx
from phoenix.client import Client

custom_http = httpx.Client(
    base_url="https://phoenix.example.com",
    headers={"Authorization": "Bearer phx_sk_abc123..."},
    timeout=httpx.Timeout(connect=5.0, read=60.0, write=10.0, pool=10.0),
)
client = Client(http_client=custom_http)

Header Resolution Order

from phoenix.client import Client

# Headers are merged with this precedence:
# 1. User headers (highest for non-auth keys)
# 2. Environment-derived headers (gap-fill)
# 3. api_key overwrites any Authorization header
client = Client(
    base_url="https://phoenix.example.com",
    api_key="phx_sk_abc123...",
    headers={"X-Custom-Header": "my-value"},
)

Related Pages

Implements Principle

Principle:Arize_ai_Phoenix_Client_Initialization

Requires Environment

Uses Heuristic

Heuristic:Arize_ai_Phoenix_Environment_Variable_Precedence

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment