curl --request POST \
--url https://api.arize.com/v2/spans \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"project_id": "my-project",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-02T00:00:00Z",
"filter": "status_code = 'ERROR'"
}
EOFimport requests
url = "https://api.arize.com/v2/spans"
payload = {
"project_id": "my-project",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-02T00:00:00Z",
"filter": "status_code = 'ERROR'"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
project_id: 'my-project',
start_time: '2024-01-01T00:00:00Z',
end_time: '2024-01-02T00:00:00Z',
filter: 'status_code = \'ERROR\''
})
};
fetch('https://api.arize.com/v2/spans', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arize.com/v2/spans",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'project_id' => 'my-project',
'start_time' => '2024-01-01T00:00:00Z',
'end_time' => '2024-01-02T00:00:00Z',
'filter' => 'status_code = \'ERROR\''
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.arize.com/v2/spans"
payload := strings.NewReader("{\n \"project_id\": \"my-project\",\n \"start_time\": \"2024-01-01T00:00:00Z\",\n \"end_time\": \"2024-01-02T00:00:00Z\",\n \"filter\": \"status_code = 'ERROR'\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.arize.com/v2/spans")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"my-project\",\n \"start_time\": \"2024-01-01T00:00:00Z\",\n \"end_time\": \"2024-01-02T00:00:00Z\",\n \"filter\": \"status_code = 'ERROR'\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/spans")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"my-project\",\n \"start_time\": \"2024-01-01T00:00:00Z\",\n \"end_time\": \"2024-01-02T00:00:00Z\",\n \"filter\": \"status_code = 'ERROR'\"\n}"
response = http.request(request)
puts response.read_body{
"spans": [
{
"name": "llm.chat.completion",
"context": {
"trace_id": "trace_001",
"span_id": "span_001"
},
"kind": "LLM",
"parent_id": "span_000",
"status_code": "OK",
"start_time": "2024-01-01T12:00:00Z",
"end_time": "2024-01-01T12:00:01Z",
"attributes": {
"llm.model_name": "gpt-4o",
"llm.token_count.prompt": 150,
"llm.token_count.completion": 50
}
}
],
"pagination": {
"next_cursor": "cursor_12345",
"has_more": true
}
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}List spans
Returns a paginated list of spans.
Spans are ordered by start_time from newest to oldest. Trace and span
identifiers give spans with the same start time a stable order. Start and
end time bounds are inclusive.
Use the returned cursor with the same project, filter, column selection, and time window. You can change the page limit. If the server rejects a cursor after an endpoint update, restart the page walk without it.
Adjacent inclusive polling windows overlap at their boundary. Remove duplicate trace and span identifier pairs. Use an overlap between polling windows to include data that arrives late. Cursor pagination keeps one time window fixed, but it is not a snapshot of changing data.
Spans that arrive long after they started
start_time is the time your application recorded for the span. Arize
also stores the time it received the span. This endpoint searches
received-time storage for a few hours on either side of the start_time
range you ask for, which is how the Arize UI reads the same data.
A span that reached Arize much later than it started can therefore fall
outside that search. Backfilled or replayed traces are the common case.
Widen start_time and end_time to cover when the data was sent, not
only when it was recorded, and those spans come back.
curl --request POST \
--url https://api.arize.com/v2/spans \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data @- <<EOF
{
"project_id": "my-project",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-02T00:00:00Z",
"filter": "status_code = 'ERROR'"
}
EOFimport requests
url = "https://api.arize.com/v2/spans"
payload = {
"project_id": "my-project",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-02T00:00:00Z",
"filter": "status_code = 'ERROR'"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
project_id: 'my-project',
start_time: '2024-01-01T00:00:00Z',
end_time: '2024-01-02T00:00:00Z',
filter: 'status_code = \'ERROR\''
})
};
fetch('https://api.arize.com/v2/spans', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arize.com/v2/spans",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'project_id' => 'my-project',
'start_time' => '2024-01-01T00:00:00Z',
'end_time' => '2024-01-02T00:00:00Z',
'filter' => 'status_code = \'ERROR\''
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.arize.com/v2/spans"
payload := strings.NewReader("{\n \"project_id\": \"my-project\",\n \"start_time\": \"2024-01-01T00:00:00Z\",\n \"end_time\": \"2024-01-02T00:00:00Z\",\n \"filter\": \"status_code = 'ERROR'\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.arize.com/v2/spans")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"my-project\",\n \"start_time\": \"2024-01-01T00:00:00Z\",\n \"end_time\": \"2024-01-02T00:00:00Z\",\n \"filter\": \"status_code = 'ERROR'\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/spans")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"my-project\",\n \"start_time\": \"2024-01-01T00:00:00Z\",\n \"end_time\": \"2024-01-02T00:00:00Z\",\n \"filter\": \"status_code = 'ERROR'\"\n}"
response = http.request(request)
puts response.read_body{
"spans": [
{
"name": "llm.chat.completion",
"context": {
"trace_id": "trace_001",
"span_id": "span_001"
},
"kind": "LLM",
"parent_id": "span_000",
"status_code": "OK",
"start_time": "2024-01-01T12:00:00Z",
"end_time": "2024-01-01T12:00:01Z",
"attributes": {
"llm.model_name": "gpt-4o",
"llm.token_count.prompt": 150,
"llm.token_count.completion": 50
}
}
],
"pagination": {
"next_cursor": "cursor_12345",
"has_more": true
}
}{
"status": 400,
"title": "Invalid request parameters",
"detail": "The 'name' field is required and must be a non-empty string.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#invalid-request"
}{
"status": 401,
"title": "Authentication required",
"detail": "You must be authenticated to access this resource.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#authentication-required"
}{
"status": 403,
"title": "Access forbidden",
"detail": "You do not have permission to access this resource.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#access-forbidden"
}{
"status": 404,
"title": "Resource not found",
"detail": "The requested resource with ID '12345' was not found.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#resource-not-found"
}{
"status": 422,
"title": "Unprocessable Entity",
"detail": "One or more fields failed validation.",
"instance": "/resource/12345",
"type": "https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity"
}{
"status": 429,
"title": "Rate limit exceeded",
"detail": "You have exceeded the allowed number of requests. Please try again later.",
"instance": "/resource",
"type": "https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded"
}Authorizations
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
Maximum items to return. Defaults to 50 if omitted; maximum is 500.
1 <= x <= 500Opaque 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
Body containing span query parameters
The project ID to list spans for
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.
Filter to spans starting at or before this timestamp (inclusive).
ISO 8601 format (e.g., 2024-01-02T00:00:00Z). Defaults to the current time.
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.
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.
1 - 1000 elements1Columns 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.
Excluding an attributes.* column removes that attribute from the
returned attributes object.
1 - 1000 elements1Response
Returns a list of spans
A list of spans ordered by start_time from newest to oldest. Spans
with the same start time use their trace and span identifiers for a
stable order.
Show child attributes
Show child attributes
Pagination metadata for cursor-based navigation. A cursor keeps the resolved time window fixed. It is valid only for the same project, filter, column selection, and sort order. A page walk is not a snapshot: data that arrives after the first request can affect later pages.
Show child attributes
Show child attributes
Was this page helpful?