Skip to main content
PyPI Version
For the complete API reference and detailed guides, see the full documentation.
Phoenix Client provides a interface for interacting with the Phoenix platform via its REST API, enabling you to manage datasets, run experiments, analyze traces, and collect feedback programmatically

Features

  • REST API Interface - Interact with Phoenix’s OpenAPI REST interface
  • Prompts - Create, version, and invoke prompt templates
  • Datasets - Create and append to datasets from DataFrames, CSV files, or dictionaries
  • Experiments - Run evaluations and track experiment results
  • Spans - Query and analyze traces with powerful filtering
  • Annotations - Add human feedback and automated evaluations
  • Sessions - Retrieve and list multi-turn conversation sessions

Installation

Install the Phoenix Client using pip:

Getting Started

Environment Variables

Configure the Phoenix Client using environment variables for seamless use across different environments:
PHOENIX_ENDPOINT is a base URL and is the canonical setting for the client. If your app also exports traces, set PHOENIX_COLLECTOR_ENDPOINT for the OTel SDK — usually to the same value. When only PHOENIX_COLLECTOR_ENDPOINT is set, the client infers its base URL from it. See Environment Variables.

Client Initialization

The client automatically reads environment variables, or you can override them:

Resources

The Phoenix Client organizes functionality into resources that correspond to key Phoenix platform features. Each resource provides specialized methods for managing different types of data:

Prompts

Manage prompt templates and versions:

Datasets

Manage evaluation datasets and examples for experiments and evaluation:

Spans

Query for spans and annotations from your projects for custom evaluation and annotation workflows:

Annotations

Add annotations to spans for evaluation, user feedback, and custom annotation workflows:

Projects

Manage Phoenix projects that organize your AI application data:

Sessions

Retrieve session data for multi-turn conversations. Sessions group related traces from a conversation into a single timeline.

Async Usage

Secrets

Create, rotate, and delete the encrypted provider credentials (such as LLM API keys) that Phoenix stores for the playground and custom AI providers. Each call is a single atomic PUT /v1/secrets request. Managing secrets requires an admin API key when authentication is enabled, and Phoenix server 13.21.0 or later.
The result lists only the keys that were upserted and deleted. Secret values are never returned, and they are left out of the method’s error messages: an httpx.HTTPStatusError raised for a rejected batch carries the status code and validation messages, but not the request body or the server’s response body. An empty batch raises ValueError before any request is sent. AsyncClient provides the same method as a coroutine:
See Secrets for how stored secrets are encrypted and used.

Reference Documentation

Full API Reference

Complete API documentation for datasets, experiments, prompts, spans, sessions, and annotations