Skip to main content
POST
List spans

Authorizations

Authorization
string
header
required

Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format

Query Parameters

limit
integer
default:50

Maximum items to return. Defaults to 50 if omitted; maximum is 500.

Required range: 1 <= x <= 500
cursor
string

Opaque pagination cursor returned from a previous response (pagination.next_cursor). Treat it as an unreadable token; do not attempt to parse or construct it.

Body

application/json

Body containing span query parameters

project_id
string
required

The project ID to list spans for

start_time
string<date-time>

Filter to spans starting at or after this timestamp (inclusive). ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Defaults to 1 week ago.

end_time
string<date-time>

Filter to spans starting before this timestamp (exclusive). ISO 8601 format (e.g., 2024-01-02T00:00:00Z). Defaults to the current time.

filter
string

Filter expression to apply to the query. Supports SQL-like syntax for filtering spans by attributes (e.g., status_code = 'ERROR'). Optional; omit it to apply no filter. If provided, it must not be empty or whitespace-only.

included_columns
string[]

Columns to include in each span. When set, only these columns (plus fixed span fields) are returned. Mutually exclusive with excluded_columns — providing both returns 422.

Values must be full dotted column paths (e.g., attributes.llm.model_name, eval.hallucination.score). Unknown column names are silently ignored.

Fixed span fields — name, context (trace_id, span_id), kind, parent_id, start_time, end_time, status_code, status_message, latency_ms, and events — are always returned regardless of this parameter.

Required array length: 1 - 1000 elements
Minimum string length: 1
excluded_columns
string[]

Columns to exclude from each span. When set, all columns except these are returned. Mutually exclusive with included_columns — providing both returns 422.

Values must be full dotted column paths (e.g., attributes.embedding.vectors, eval.toxicity.score). Unknown column names are silently ignored. Attempts to exclude fixed span fields (name, context, kind, parent_id, start_time, end_time, status_code, status_message, latency_ms, events) are silently ignored.

Required array length: 1 - 1000 elements
Minimum string length: 1

Response

Returns a list of spans

spans
object[]
required

A list of spans

pagination
object
required

Pagination metadata for cursor-based navigation