REST API Overview

Use the REST API when you want to script Phoenix workflows: creating datasets, running experiments, querying spans, or managing prompts and projects. Use the API Reference page for the full endpoint list.

Full interactive endpoint list

Browse every endpoint grouped by resource.

Before You Call The API

Choose your base URL

A remote deployment: https://your-phoenix.example.com
Self-hosted Phoenix: your deployment URL (for example http://localhost:6006)

Set authentication (if enabled)

Use an API key or admin secret in a bearer token header:Authorization: Bearer <your-token>

Call a v1 endpoint

All REST endpoints are under /v1/....

If authentication is disabled in your self-hosted deployment, you can omit the Authorization header.

First Request

The example below lists projects and includes common pagination query params.

cURL
JavaScript
Python

curl --request GET \
  --url "$PHOENIX_ENDPOINT/v1/projects?limit=10" \
  --header "Authorization: Bearer $PHOENIX_API_KEY"

const baseUrl = process.env.PHOENIX_ENDPOINT;
const apiKey = process.env.PHOENIX_API_KEY;

const response = await fetch(
  `${baseUrl}/v1/projects?limit=10`,
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

const body = await response.json();
console.log(body.data);

import os
import requests

base_url = os.environ["PHOENIX_ENDPOINT"]
api_key = os.environ.get("PHOENIX_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}

response = requests.get(
    f"{base_url}/v1/projects",
    params={"limit": 10},
    headers=headers,
    timeout=30,
)
response.raise_for_status()

body = response.json()
print(body["data"])

Response Pattern

Most list endpoints return a shape like:

{
  "data": [],
  "next_cursor": null
}

When next_cursor is not null, pass it back as the cursor query param to fetch the next page.

Chat Completions Proxy

POST /v1/chat/completions accepts the OpenAI wire format and proxies the call to the provider you name, resolving provider credentials on the server (secret store first, environment second) so callers never handle provider API keys.

Phoenix is not an AI gateway. The same server also takes on trace ingestion traffic, so routing production LLM calls through it competes with ingestion. Use this endpoint only to quickly try out different models in non-production environments.

Set model to {provider}:{model_name} for a built-in provider, or custom:{provider_id}:{model_name} for a custom provider you have stored. Pass stream: true for server-sent chat.completion.chunk events terminated by data: [DONE]. Tool calling is not supported.

curl --request POST \
  --url "$PHOENIX_BASE_URL/v1/chat/completions" \
  --header "Authorization: Bearer $PHOENIX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai:gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Where To Go Next

Projects

Start by listing projects and finding your project identifier.

Spans

Query spans for a project.

Datasets

Create and manage evaluation datasets.

Prompts

Manage prompt versions and tags.

Python

TypeScript

Rest API

OpenInference SDK

REST API Overview

Full interactive endpoint list

Before You Call The API

First Request

Response Pattern

Chat Completions Proxy

Where To Go Next

Projects

Spans

Datasets

Prompts

Full interactive endpoint list

​Before You Call The API

​First Request

​Response Pattern

​Chat Completions Proxy

​Where To Go Next

Projects

Spans

Datasets

Prompts

Before You Call The API

First Request

Response Pattern

Chat Completions Proxy

Where To Go Next