List spans with simple filters (no DSL)

Return spans within a project filtered by time range. Supports cursor-based pagination.

project_identifierstring required

The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.

cursorstring nullable

Pagination cursor (Span Global ID)

limitinteger

Maximum number of spans to return

start_timestring date-time nullable

Inclusive lower bound time

end_timestring date-time nullable

Exclusive upper bound time

trace_idstring[] nullable

Filter by one or more trace IDs

span_idstring[] nullable

Filter by one or more span IDs

parent_idstring nullable

Filter by parent span ID. Use "null" to get root spans only.

namestring[] nullable

Filter by span name(s)

span_kindstring[] nullable

Filter by span kind(s). Values: LLM, CHAIN, TOOL, RETRIEVER, EMBEDDING, AGENT, RERANKER, GUARDRAIL, EVALUATOR, UNKNOWN

status_codestring[] nullable

Filter by status code(s). Values: OK, ERROR, UNSET

attributestring[] nullable

Filter spans by key:value. Key is a dot-path (e.g. user.id, metadata.tier). Value is JSON-parsed: k:12345 is int, k:true is bool, otherwise string (k:user-42). To match a numeric- or boolean-looking STRING, JSON-quote it: user.id:"12345" (URL-encoded %2212345%22). Split is on the first : only, so values may contain colons (session.id:sess:abc:123, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. tag.tags) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value).

Response

Successful Response

next_cursorstring nullable required

Example response

{
  "data": [
    {
      "attributes": {
        "llm.model_name": "gpt-4",
        "llm.token_count.completion": 50,
        "llm.token_count.prompt": 100
      },
      "context": {
        "span_id": "1a2b3c4d5e6f7a8b",
        "trace_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
      },
      "end_time": "2024-01-01T12:00:01Z",
      "events": [],
      "name": "llm_call",
      "span_kind": "LLM",
      "start_time": "2024-01-01T12:00:00Z",
      "status_code": "OK",
      "status_message": ""
    }
  ]
}

v55

List spans with simple filters (no DSL)

Path parameters

Query parameters

Response

Example response