> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Traces are returned newest-first.
**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 by `root_span_id`.
- Each trace returns at most 1,000 spans. When a trace has more, its
`spans_truncated` flag is `true`.
This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).
## OpenAPI
````yaml https://api.arize.com/v2/spec.yaml post /v2/traces
openapi: 3.0.3
info:
title: Arize REST API
version: 2.0.0
description: |
API specification for the backend data server. The API is hosted globally
at https://api.arize.com/v2 or in your own environment.
license:
name: Apache-2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- description: Global
url: https://api.arize.com
- description: Regional
url: https://api.{region}.arize.com
variables:
region:
default: eu-west-1a
enum:
- eu-west-1a
- ca-central-1a
- description: Custom Host
url: https://{host}
variables:
host:
default: api.arize.com
security:
- bearerAuth: []
tags:
- name: AI Integrations
description: |
AI integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
entire account, a specific organization, or a specific space.
- name: Annotation Configs
description: >
Annotation configs allow you to define consistent annotation schemas that
can be reused across your workspace, ensuring evaluations are structured
and
comparable over time.
- name: Annotation Queues
description: >
Annotation queues help you organize and manage human evaluation workflows.
Use queues to assign spans or examples to annotators for review and
labeling.
- name: API Keys
description: >
API keys are used to authenticate requests to the Arize API. List your
keys
to view metadata; the raw secret is never returned after creation.
- name: Audit Logs
description: >
Audit logs record authenticated user actions within an account, providing
a
chronological trail for security and compliance review. Access requires
account admin privileges and audit logging to be enabled.
- name: Datasets
description: |
Datasets are structured, version-controlled example collections you use to
run, evaluate, and track LLM experiments.
- name: Evaluators
description: >
Evaluators are reusable evaluation configurations used to assess the
quality
of LLM outputs. They can be template-based (using LLM judges) or
code-based.
- name: Experiments
description: >
Experiments let you systematically test prompt/model changes using
datasets,
tasks, and evaluators.
- name: Integrations
description: >
Integrations configure access to external LLM providers (e.g. OpenAI,
Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
PagerDuty, Slack), and
your own agents. Integrations can be scoped to the entire account, a
specific
organization, or a specific space.
- name: Monitors
description: >
Monitors continuously track a metric over your model or LLM application
data
and alert you when it crosses a threshold. Each monitor watches a single
metric - data quality, model performance, drift, a custom metric, or a
tracing metric - and moves between statuses as the metric passes in and
out of its
healthy range.
- name: Organizations
description: >
Organizations are top-level containers within an Arize AX account for
grouping spaces.
- name: Projects
description: |
Projects represent LLM applications being monitored in Arize where you can
observe traces and spans.
- name: Prompts
description: >
Prompts are reusable, versioned templates for LLM interactions. Use
prompts
to standardize and manage how you interact with LLMs across your
application.
- name: Resource Restrictions
description: |
Endpoints for restricting and unrestricting resources (projects, models).
- name: Role Bindings
description: |
Role bindings assign a role to a user on a resource. REST currently
supports space- and project-scoped bindings.
- name: Roles
description: >
Roles define sets of permissions that can be assigned to users within an
account. Create custom roles to tailor access control to your team's
needs.
- name: Spaces
description: >
Spaces are containers within an organization for grouping related
projects,
datasets, and experiments, enabling collaboration or isolated
experimentation
with role-based access control.
- name: Spans
description: |
Spans represent individual operations within a trace. A span captures the
timing, status, and attributes of a single operation in your application.
- name: Tasks
description: |
Tasks are configurable units of work that tie one or more evaluators to a
data source (project or dataset). Use tasks to automate evaluation of LLM
outputs, with support for continuous evaluation and backfill runs.
- name: Traces
description: |
A trace is the collection of spans sharing a trace ID, representing a
single end-to-end request through an LLM application. Use the Traces
endpoint to retrieve traces with all of their spans in one call.
- name: Users
description: >
Users represent members of an account. The Users endpoints allow creating,
listing, updating (display name), and removing users from the account
programmatically.
- name: Webhooks
description: >
Webhooks are organization-owned destinations that receive event deliveries
over HTTPS. Deliveries are authenticated with a bearer token or signed
with
an HMAC signing secret — the secret is returned exactly once, when the
webhook is created. Delivery attempts are recorded and can be listed for
debugging. To choose which events a webhook receives, manage its
subscriptions through the prompt and evaluator webhook-subscription
endpoints.
paths:
/v2/traces:
post:
tags:
- Traces
summary: List traces
description: >
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.
Traces are returned newest-first.
**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 by `root_span_id`.
- Each trace returns at most 1,000 spans. When a trace has more, its
`spans_truncated` flag is `true`.
This endpoint is in beta, read more
[here](https://arize.com/docs/ax/rest-reference#api-version-stages).
operationId: list_traces
parameters:
- $ref: '#/components/parameters/LimitQueryParamMax50'
- $ref: '#/components/parameters/CursorQueryParam'
requestBody:
$ref: '#/components/requestBodies/ListTracesRequestBody'
responses:
'200':
$ref: '#/components/responses/ListTracesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
parameters:
LimitQueryParamMax50:
name: limit
in: query
description: Maximum items to return
schema:
type: integer
minimum: 1
maximum: 50
default: 25
CursorQueryParam:
name: cursor
in: query
description: |
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.
schema:
type: string
requestBodies:
ListTracesRequestBody:
description: Body containing trace query parameters
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListTracesRequest'
example:
project_id: my-project
start_time: '2024-01-01T00:00:00Z'
end_time: '2024-01-02T00:00:00Z'
filter: status_code = 'ERROR'
responses:
ListTracesResponse:
description: Returns a list of traces
content:
application/json:
schema:
$ref: '#/components/schemas/ListTracesResponse'
example:
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
BadRequest:
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
Unauthorized:
description: Authentication is required
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
Forbidden:
description: Insufficient permissions to access this resource
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
NotFound:
description: Not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
UnprocessableEntity:
description: Unprocessable entity
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
RateLimitExceeded:
description: Rate limit exceeded
headers:
Retry-After:
description: |
When throttled (429), how long to wait before retrying. Value is
either a delta-seconds integer.
schema:
type: integer
minimum: 0
example: 42
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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
schemas:
ListTracesRequest:
type: object
required:
- project_id
additionalProperties: false
properties:
project_id:
type: string
description: The project ID to list traces for
start_time:
type: string
format: date-time
description: >
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.
end_time:
type: string
format: date-time
description: >
Return traces whose spans start before this timestamp (exclusive).
ISO 8601 format (e.g., `2024-01-02T00:00:00Z`). Defaults to the
current time.
filter:
type: string
description: >
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.
ListTracesResponse:
type: object
required:
- traces
- pagination
additionalProperties: false
x-forward-compatible: true
properties:
traces:
type: array
items:
$ref: '#/components/schemas/Trace'
description: A list of traces, ordered newest-first.
pagination:
$ref: '#/components/schemas/PaginationMetadata'
description: Pagination metadata for cursor-based navigation
Problem:
type: object
description: RFC 9457 Problem Details
properties:
title:
type: string
description: A short, human-readable summary of the problem type
status:
type: integer
description: >-
The HTTP status code generated by the origin server for this
occurrence of the problem
type:
type: string
format: uri-reference
description: A URI reference that identifies the problem type
detail:
type: string
description: >-
A human-readable explanation specific to this occurrence of the
problem
instance:
type: string
format: uri-reference
description: >-
A URI reference that identifies the specific occurrence of the
problem
required:
- title
- status
additionalProperties: false
x-forward-compatible: true
Trace:
type: object
required:
- trace_id
- root_span_id
- spans_truncated
- spans
additionalProperties: false
x-forward-compatible: true
properties:
trace_id:
type: string
description: Unique identifier for the trace.
root_span_id:
type: string
description: |
Span ID of the root span (the span with no parent) that anchors this
trace entry. A trace with more than one root span is returned as
multiple entries sharing the same `trace_id`, distinguished by
`root_span_id`.
start_time:
type: string
format: date-time
description: Earliest span start time across the returned spans.
end_time:
type: string
format: date-time
description: Latest span end time across the returned spans.
spans_truncated:
type: boolean
description: >
`true` when this trace contained more spans than the per-trace limit
and
its returned span list is incomplete. `false` otherwise.
Note: each page also has an overall cap on the total number of spans
returned across all of its traces. On pages that include unusually
large
traces, an individual trace may return fewer spans than it actually
has
even when `spans_truncated` is `false`. To retrieve a trace's spans
in
full, narrow the time window or fetch them directly with
`POST /v2/spans` filtered to that `trace_id`.
spans:
type: array
items:
$ref: '#/components/schemas/Span'
description: >
Flat list of spans belonging to this trace. Each span has the same
shape
and enrichment as spans returned by `POST /v2/spans`. Reconstruct
the
trace tree client-side using each span's `parent_id`.
description: >
A Trace is the collection of spans sharing a `trace_id`, anchored on a
root
span (a span with no parent). It captures a single end-to-end request
through an LLM application, with lightweight roll-up metadata plus the
full
flat list of its spans.
PaginationMetadata:
required:
- has_more
type: object
properties:
next_cursor:
type: string
description: >
Opaque cursor for fetching the next page. Treat as an unreadable
token.
Present when `has_more` is true; omitted when `has_more` is false.
has_more:
type: boolean
description: True if another page of results is available.
description: |
Cursor-based pagination metadata. Use `next_cursor` in the subsequent
request's `cursor` query parameter.
additionalProperties: false
x-forward-compatible: true
Span:
type: object
required:
- kind
- name
- context
- start_time
- end_time
properties:
name:
type: string
description: Name of the span
context:
$ref: '#/components/schemas/SpanContext'
description: The trace and span identifiers for this span
kind:
$ref: '#/components/schemas/SpanKind'
description: The kind of span (OpenInference span kind).
parent_id:
type: string
description: ID of the parent span
start_time:
type: string
format: date-time
description: Timestamp when the span started
end_time:
type: string
format: date-time
description: Timestamp when the span ended
status_code:
allOf:
- $ref: '#/components/schemas/SpanStatusCode'
description: >-
Status code of the span. When absent, the server treats the value as
`UNSET` (equivalent to OK).
status_message:
type: string
description: Status message associated with the span
attributes:
type: object
additionalProperties: true
description: Key-value pairs of span attributes
annotations:
type: array
items:
$ref: '#/components/schemas/Annotation'
description: List of span-level human annotations on this span
trace_annotations:
type: array
items:
$ref: '#/components/schemas/Annotation'
description: List of trace-level human annotations on this span
evaluations:
type: array
items:
$ref: '#/components/schemas/Evaluation'
description: List of evaluation results on this span
events:
type: array
items:
$ref: '#/components/schemas/SpanEvent'
description: List of events that occurred during the span
description: >
A Span represents a single unit of work within a distributed trace for
an LLM application.
It captures the operation’s input and output, start and end times, and a
span kind indicating its role (such as LLM, Tool, Agent, Retriever,
Chain, or Embedding).
Spans are hierarchically related and combine to form a trace, enabling
end-to-end visibility into request execution, performance bottlenecks,
and errors across complex LLM pipelines.
additionalProperties: false
x-forward-compatible: true
SpanContext:
type: object
required:
- trace_id
- span_id
properties:
trace_id:
type: string
description: Unique identifier for the trace this span belongs to
span_id:
type: string
description: Unique identifier for the span
additionalProperties: false
x-forward-compatible: true
SpanKind:
type: string
x-extensible-enum: true
enum:
- LLM
- CHAIN
- RETRIEVER
- EMBEDDING
- AGENT
- TOOL
- RERANKER
- GUARDRAIL
- EVALUATOR
- PROMPT
- UNKNOWN
description: The kind of span (OpenInference span kind).
SpanStatusCode:
type: string
enum:
- OK
- ERROR
- UNSET
description: |
Status code of the span.
- OK - The operation completed successfully.
- ERROR - The operation failed with an error.
- UNSET - No status code was set (default, treated as OK).
Annotation:
type: object
description: A human annotation on a record.
required:
- name
properties:
name:
type: string
description: The name of the annotation
score:
type: number
format: double
description: Numeric score for the annotation
label:
type: string
description: Categorical label for the annotation
text:
type: string
description: Free-form text note for the annotation
updated_at:
type: string
format: date-time
description: Timestamp when the annotation was last updated
annotator:
allOf:
- $ref: '#/components/schemas/AnnotatorUser'
description: The user who made this annotation
additionalProperties: false
x-forward-compatible: true
Evaluation:
type: object
description: An evaluation result on a record.
required:
- name
properties:
name:
type: string
description: The name of the evaluation
score:
type: number
format: double
description: Numeric score for the evaluation
label:
type: string
description: Categorical label for the evaluation
explanation:
type: string
description: Explanation for the evaluation result
additionalProperties: false
x-forward-compatible: true
SpanEvent:
type: object
required:
- name
- timestamp
properties:
name:
type: string
description: Name of the event
timestamp:
type: string
format: date-time
description: Timestamp when the event occurred
attributes:
type: object
additionalProperties: true
description: Key-value pairs of event attributes
additionalProperties: false
x-forward-compatible: true
AnnotatorUser:
type: object
description: A user assigned as an annotator, identified by ID and email.
required:
- id
- email
properties:
id:
type: string
description: The unique identifier for the user
email:
$ref: '#/components/schemas/Email'
additionalProperties: false
x-forward-compatible: true
Email:
type: string
format: email
description: An email address
example: user@example.com
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat:
description: >
Most Arize AI endpoints require authentication. For those endpoints that
require authentication, include your API key in the request header using
the format
``` Authorization: Bearer
```
````