Spans

List spans

Changed on

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.

<Note>This endpoint is in beta, read more here.</Note>

post/v2/spans

Request

  • Base URL
    https://api.arize.com
  • URL
    https://api.arize.com/v2/spans
  • Auth
    HTTP bearer

Query parameters

limitinteger

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

cursorstring

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.

Request body

project_idstring required

The project ID to list spans for

start_timestring 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_timestring date-time

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.

filterstring

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_columnsstring[]

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.

excluded_columnsstring[]

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.

Excluding an attributes.* column removes that attribute from the returned attributes object.

truncate_string_lengthinteger

When set, every string value inside each returned span's attributes object, including strings nested at any depth in objects and arrays, is shortened to at most this many characters (Unicode code points). Strings longer than the limit are cut and end with a single ellipsis character … which counts toward the limit; strings at or under the limit are unchanged. Only attributes string values are affected; span IDs, names, kinds, status, timestamps, annotations, evaluations, events and pagination are never truncated. Omitted means no truncation. Must be a positive integer; 0 or negative returns 422.

Response

Returns a list of spans

Example response

{
  "spans": [
    {
      "annotations": [
        {
          "annotator": {
            "email": "user@example.com"
          }
        }
      ],
      "trace_annotations": [
        {
          "annotator": {
            "email": "user@example.com"
          }
        }
      ]
    }
  ]
}

Changes