latestOpenAPI 3.0.3Apache-2.02026-08-21144388693.7 KB

c26a00e9b318

Spans

List spans

Returns a paginated list of spans.

The spans are sorted by their timestamp, with the most recent coming first.

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

post/v2/spans

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 before this timestamp (exclusive). 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.

Response

Returns a list of spans

Example response

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