curl --request POST \
--url https://api.arize.com/v2/traces \
--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/traces"
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/traces', 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/traces",
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/traces"
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/traces")
.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/traces")
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{
"traces": [
{
"trace_id": "trace_001",
"root_span_id": "span_000",
"start_time": "2024-01-01T12:00:00Z",
"end_time": "2024-01-01T12:00:03Z",
"spans_truncated": false,
"spans": [
{
"name": "agent.run",
"context": {
"trace_id": "trace_001",
"span_id": "span_000"
},
"kind": "AGENT",
"status_code": "OK",
"start_time": "2024-01-01T12:00:00Z",
"end_time": "2024-01-01T12:00:03Z"
},
{
"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:01Z",
"end_time": "2024-01-01T12:00:02Z",
"attributes": {
"llm.model_name": "gpt-4o"
}
}
]
}
],
"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 traces
Returns a paginated list of traces for a project, each carrying its full
(flat) list of spans plus lightweight roll-up metadata. It accepts the
same project_id, filter, and time-range parameters as POST /v2/spans;
the filter uses the identical expression syntax, so there’s no separate
filter language to learn.
Filtering is trace-contains-match: the syntax matches /v2/spans, but
the semantics differ — a filter selects traces that contain at least one
matching span (e.g. status_code = 'ERROR' or span_kind = 'LLM'), not
only traces whose root span matches. The matching span is usually a child,
not the root.
Trace entries are ordered by root span start_time from newest to oldest.
Root trace and span identifiers give entries with the same start time a
stable order. Start and end time bounds are inclusive.
Behaviors and limitations
- Traces are anchored on their root span (the span with no parent). A trace with no root span in the requested time window is omitted.
- Trace assembly is scoped to the requested time window: spans of a boundary-straddling trace that fall outside the range are not included.
- A trace with more than one root span is returned as multiple entries
sharing the same
trace_id, distinguished byroot_span_id. - Each trace returns at most 1,000 spans. Traces share a fetch allowance
per page. When that allowance is exhausted, traces can be incomplete
even when
spans_truncatedisfalse.
Use the returned cursor with the same project, filter, 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. Cursor pagination keeps one time window fixed, but it is not a snapshot of changing data.
Traces 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 trace 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 traces come back.
curl --request POST \
--url https://api.arize.com/v2/traces \
--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/traces"
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/traces', 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/traces",
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/traces"
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/traces")
.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/traces")
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{
"traces": [
{
"trace_id": "trace_001",
"root_span_id": "span_000",
"start_time": "2024-01-01T12:00:00Z",
"end_time": "2024-01-01T12:00:03Z",
"spans_truncated": false,
"spans": [
{
"name": "agent.run",
"context": {
"trace_id": "trace_001",
"span_id": "span_000"
},
"kind": "AGENT",
"status_code": "OK",
"start_time": "2024-01-01T12:00:00Z",
"end_time": "2024-01-01T12:00:03Z"
},
{
"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:01Z",
"end_time": "2024-01-01T12:00:02Z",
"attributes": {
"llm.model_name": "gpt-4o"
}
}
]
}
],
"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 25 if omitted; maximum is 50.
1 <= x <= 50Opaque 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 trace query parameters
The project ID to list traces for
Return traces whose spans start at or after this timestamp (inclusive).
ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Defaults to 1 week ago.
Return traces whose spans start 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' or
span_kind = 'LLM'). A trace is returned when any of its spans
matches the filter — the matching span is usually a child, not the root.
Optional; omit it to apply no filter. If provided, it must not be empty
or whitespace-only.
Response
Returns a list of traces
A list of root-based trace entries ordered by root span start_time
from newest to oldest. The root trace and span identifiers give entries
with the same start time a stable order.
Show child attributes
Show child attributes
Pagination metadata for cursor-based navigation. A cursor keeps the resolved time window fixed and applies only to root selection. It is valid only for the same project, filter, 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?