v4

latestOpenAPI 3.1.02026-08-019681,1012.0 MB

trace

Query Spans

post/projects/{project_id}/spans/search

Path parameters

project_idstring uuid4 required

Request body

starting_tokeninteger

limitinteger

previous_last_row_idstring uuid4 nullable

log_stream_idstring uuid4 nullable

Log stream id associated with the traces.

experiment_idstring uuid4 nullable

Experiment id associated with the traces.

metrics_testing_idstring uuid4 nullable

Metrics testing id associated with the traces.

truncate_fieldsboolean

include_countsboolean

If True, include computed child counts (e.g., num_traces for sessions, num_spans for traces).

include_code_metric_metadataboolean

If True, include per-row scorer metadata (the dict returned alongside the score by code-based scorers via the (score, metadata) tuple-return contract) on each MetricSuccess in the response. Off by default to keep payloads small for callers that don't need it.

Example request

{
  "filters": [
    {
      "case_sensitive": true,
      "name": "input",
      "operator": "eq",
      "type": "text",
      "value": "example input"
    }
  ],
  "log_stream_id": "00000000-0000-0000-0000-000000000000",
  "pagination": {
    "limit": 5,
    "starting_token": 0
  },
  "sort": {
    "ascending": false,
    "name": "updated_at",
    "sort_type": "column"
  }
}

Response

Successful Response

starting_tokeninteger

limitinteger

paginatedboolean

next_starting_tokeninteger nullable

last_row_idstring uuid4 nullable

num_recordsinteger required

number of records

Example response

{
  "next_starting_token": 2,
  "num_rows": 2,
  "paginated": true,
  "records": [
    {
      "annotation_aggregates": {},
      "annotation_agreement": {},
      "annotation_queue_ids": [],
      "annotations": {},
      "created_at": "2026-07-27T17:31:56.130026Z",
      "dataset_metadata": {},
      "error_message": "",
      "feedback_rating_info": {},
      "file_ids": [],
      "file_modalities": [],
      "id": "1a0939d1-8b43-4fe3-a91c-196e2d9847e3",
      "input": "Who is a smart LLM?",
      "is_complete": true,
      "metrics": {
        "duration_ns": 4
      },
      "name": "",
      "output": "I am",
      "progress_message": "",
      "project_id": "0d4e3799-3861-4759-875f-9ae14c167b0a",
      "run_id": "74aec44e-ec21-4c9f-a3e2-b2ab2b81b4db",
      "session_id": "1a0939d1-8b43-4fe3-a91c-196e2d9847e3",
      "tags": [],
      "trace_id": "1a0939d1-8b43-4fe3-a91c-196e2d9847e3",
      "type": "trace",
      "user_metadata": {}
    },
    {
      "annotation_aggregates": {},
      "annotation_agreement": {},
      "annotation_queue_ids": [],
      "annotations": {},
      "created_at": "2026-07-27T17:31:56.130216Z",
      "dataset_metadata": {},
      "error_message": "",
      "feedback_rating_info": {},
      "file_ids": [],
      "file_modalities": [],
      "id": "1edc2401-24b4-448c-a392-b36932293061",
      "input": [
        {
          "content": "Who is a smart LLM?",
          "role": "user"
        }
      ],
      "is_complete": true,
      "metrics": {
        "duration_ns": 4,
        "num_input_tokens": 4,
        "num_output_tokens": 2,
        "num_total_tokens": 6
      },
      "name": "",
      "output": {
        "content": "I am",
        "role": "user"
      },
      "parent_id": "1a0939d1-8b43-4fe3-a91c-196e2d9847e3",
      "progress_message": "",
      "project_id": "0d4e3799-3861-4759-875f-9ae14c167b0a",
      "run_id": "74aec44e-ec21-4c9f-a3e2-b2ab2b81b4db",
      "session_id": "1a0939d1-8b43-4fe3-a91c-196e2d9847e3",
      "tags": [],
      "trace_id": "1a0939d1-8b43-4fe3-a91c-196e2d9847e3",
      "type": "llm",
      "user_metadata": {}
    }
  ]
}