REST API Overview

Start here to call the Phoenix REST API: endpoint setup, authentication, and your first request.

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

1. Choose your base URL

   • Phoenix Cloud: https://app.phoenix.arize.com
   • Self-hosted Phoenix: your deployment URL (for example http://localhost:6006)
2. Set authentication (if enabled)

   Use an API key or admin secret in a bearer token header:

   Authorization: Bearer <your-token>

3. 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

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

JavaScript

const baseUrl = process.env.PHOENIX_BASE_URL;
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);

Python

import os
import requests

base_url = os.environ["PHOENIX_BASE_URL"]
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.

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.