Welcome to the Arize REST API. This API is the programmatic interface to the Arize AX platform—designed so that every capability we offer can be discovered, automated, and integrated into your workflows. While the current release exposes core resources (e.g., datasets and experiments), our long-term vision is that the entire product line will be accessible and controllable via this API. The API follows modern REST conventions with JSON payloads, standard HTTP status codes, cursor-based pagination, structured error responses, and sensible rate limits. It is versioned to preserve backwards compatibility as we evolve (e.g., /v2/…) and is available globally as well as with regional endpoints. Authentication is simple and secure via API keys, and first-party SDKs provide idiomatic access for popular languages. Use this API to:

Integrate Arize capabilities into CI/CD, data pipelines, and internal tools
Automate creation, management, and analysis of resources across your account
Build custom workflows and dashboards on top of the Arize AX platform primitives

API Design Principles

The Arize REST API follows a CRUDL design pattern — Create, Read, Update, Delete, and List — providing a predictable, consistent interface across all resources. This means that once you learn how to interact with one resource, you’ll know how to interact with others.

Operation	HTTP Method	Typical Path	Description
List	`GET`	`/v2/{resource}`	Returns a paginated list of resources, often with filtering or sorting options.
Create	`POST`	`/v2/{resource}`	Creates a new resource. The request body includes the required fields; the response returns the newly created object.
Read	`GET`	`/v2/{resource}/{id}`	Retrieves a single resource by its unique identifier.
Update	`PATCH` or `PUT`	`/v2/{resource}/{id}`	Updates part or all of an existing resource. Some endpoints support versioned or in-place updates.
Delete	`DELETE`	`/v2/{resource}/{id}`	Permanently removes a resource. Deletes are irreversible.

Why CRUDL?

Predictable: Every resource behaves consistently — you always know which verbs to use.
Composable: Enables automation and integration with existing REST-friendly tooling.
Extensible: New resources can adopt the same verbs and structure without breaking changes.
Safe and versioned: Operations that modify data are versioned and validated to preserve data integrity.

API Version Stages

Our API evolves through three release stages — Alpha, Beta, and Stable — to introduce new functionality safely, with clear expectations for reliability and frequency of change. Each endpoint includes a release stage label that indicates its level of stability:

Stage	Purpose	Reliability	Recommended for
Alpha	Early development & experimentation	Experimental: Breaking changes expected	Developers exploring new capabilities
Beta	Validation & feedback of mostly complete features through real world use	Mostly stable: minor changes possible, breaking changes rare	Teams seeking early access willing tolerate minor instability
Stable	Production ready	Backwards compatible, no breaking changes	All production integrations

API Hosts & Regions

Arize operates in multiple environments to support the deployment needs of enterprises. You can send requests to the global API for standard usage or to a regional endpoint when compliance and data residency are required. Enterprise customers may also configure custom hosts for private or on-premise installations.

Environment	Base URL	Available Regions	Notes
Global	https://api.arize.com/v2	N/A	Recommended for most users. Routes automatically to the nearest global endpoint.
Regional	https://api.{region}.arize.com/v2	us-central-1a us-east-1b ca-central-1a eu-west-1a	Use for compliance and data residency requirements.
Custom Host	scheme://host/v2	Custom	For on-premise, private cloud, or enterprise environments.

Authentication

Most endpoints require authentication with an API key, sent in the HTTP request header:

Authorization: Bearer <api-key>

The API works with both User Keys and Service Keys interchangeably.

Authorization

Authorization determines what an authenticated caller is allowed to do. The API uses standard HTTP status codes to communicate authorization outcomes, with a deliberate security consideration around 403 vs 404 responses.

Status Codes

Code	Meaning	When it’s returned
`2xx`	Authorized	The caller has permission to perform the requested action.
`403`	Forbidden	The caller is authenticated and can read the resource, but lacks permission for the requested action (e.g., attempting to delete a resource they can only view).
`404`	Not Found	The caller has no read access to the resource — or the resource does not exist.

Why 404 instead of 403?

You may notice that the API sometimes returns 404 where you might expect 403. This is intentional. Without this behavior, an attacker with limited access could probe the API by attempting actions on arbitrary resource IDs. A consistent 403 response would confirm that a resource exists at that ID, allowing enumeration of resources the caller was never meant to know about. By returning 404 when the caller has no read access, the API makes “not found” and “no access” indistinguishable — preventing unauthorized callers from using error codes to discover resources.

Decision logic

Has permission for this action?  →  2xx (proceed)
Can read the resource, but lacks permission for this action?  →  403 Forbidden
Cannot read the resource (or it doesn't exist)?  →  404 Not Found

If you receive a 404 and believe the resource exists, verify that your API key has read access to the space or project containing the resource.

Response Format

All Arize API endpoints return structured JSON responses designed to be predictable, human-readable, and machine-parsable. Each response falls into one of two categories: success responses or error responses.

Success Responses

Successful responses (2xx status codes) return the requested data in JSON format. Example:

{
  "id": "RGF0YXDk3MFNldoDzMTc3MpWbQ==",
  "name": "dataset name",
  "spaceId": "U3BhYiRnVM2U6MTp",
  "createdAt": "2025-10-08T03:24:38.014847Z",
  "updatedAt": "2025-10-08T03:24:38.014847Z",
  "versions": [
    {
      "id": "RGF0Npb246MzE4NDg5OkhYXNldFZlcnQQ00=",
      "name": "dataset version name",
      "datasetId": "RGF0YXDk3MFNldoDzMTc3MpWbQ==",
      "createdAt": "2025-10-08T03:24:38.060322Z",
      "updatedAt": "2025-10-08T03:24:38.014847Z"
    }
  ]
}

Pagination

Most list endpoints implement cursor-based pagination, while others include pagination fields for forward compatibility. This ensures client applications remain stable as pagination support expands over time.

Use the limit query parameter to control the number of items per request.
When more data is available, the response includes:
- hasMore: true — indicates additional pages exist.
- nextCursor — an opaque string token used to fetch the next page.

The few endpoints that don’t have pagination implemented yet will return hasMore accurately but the nextCursor will always be missing.

{
  "datasets": [ /* items */ ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJvZmZzZXQiOiIyMDI1LTEw..."
  }
}

Error Responses

Error responses (4xx and 5xx) use the RFC 9457 Problem Details format with Content-Type: application/problem+json.

{
  "status": 404,
  "title": "Not Found",
  "type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found",
  "detail": "Dataset with ID 'abc123' was not found."
}

See the Error Reference for the complete list of status codes, type URIs, and client handling guidance.

Handling 429 responses

When you receive a 429, pause and retry after the window resets (1 minute from your first request in the current window). For long-running automation scripts, consider adding a small delay between requests or batching operations to stay within limits.

Rate Limits

The API enforces rate limits to ensure availability for all users. Limits are applied per user (all of that user’s API keys share one bucket), per endpoint, on a fixed one-minute window, and each endpoint’s limit is tracked independently, i.e., hitting a limit on one endpoint does not affect others. Default: 100 requests per minute. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header holding the seconds left in the window. Wait for the window to reset before retrying.

Need bulk access to spans? POST /v2/spans in the table below is the List spans search endpoint, capped at 500 spans per page, so at 10 requests per minute it tops out around 5,000 spans per minute. For exports, warehouse replication, or backfills, use Arrow Flight, Data Fabric, or batch span logging instead; see Choosing an interface.

Endpoint-specific limits Some endpoints have stricter limits due to the nature of their operations:

Endpoint	Method	Limit
`/v2/api-keys`	`POST`	20 / minute
`/v2/api-keys/{api_key_id}/refresh`	`POST`	10 / minute
`/v2/users/{user_id}/resend-invitation`	`POST`	20 / 5 minutes
`/v2/users/{user_id}/reset-password`	`POST`	20 / 5 minutes
`/v2/spans`	`POST`	10 / minute
`/v2/spans`	`DELETE`	10 / minute
`/v2/annotation-queues`	`POST`	10 / minute
`/v2/annotation-queues/{annotation_queue_id}/records`	`GET`	10 / minute
`/v2/annotation-queues/{annotation_queue_id}/records`	`POST`	10 / minute
`/v2/annotation-queues/{annotation_queue_id}/records/{annotation_queue_record_id}/annotate`	`POST`	50 / minute
`/v2/datasets/{dataset_id}/examples/annotate`	`POST`	10 / minute
`/v2/experiments/{experiment_id}/runs/annotate`	`POST`	10 / minute
`/v2/spans/annotate`	`POST`	10 / minute

Support

Need help integrating the API or running experiments?

Join our Slack Community
Email us at support@arize.com

Skills

MCP server

API reference

API clients

Arize REST API

API Design Principles

Why CRUDL?

API Version Stages

API Hosts & Regions

Authentication

Authorization

Status Codes

Why 404 instead of 403?

Decision logic

Response Format

Success Responses

Error Responses

Handling 429 responses

Rate Limits

Support

​API Design Principles

​Why CRUDL?

​API Version Stages

​API Hosts & Regions

​Authentication

​Authorization

​Status Codes

​Why 404 instead of 403?

​Decision logic

​Response Format

​Success Responses

​Pagination

​Error Responses

​Handling 429 responses

​Rate Limits

​Support

API Design Principles

Why CRUDL?

API Version Stages

API Hosts & Regions

Authentication

Authorization

Status Codes

Why 404 instead of 403?

Decision logic

Response Format

Success Responses

Pagination

Error Responses

Handling 429 responses

Rate Limits

Support