Skip to main content
Opik Documentation

Search documentation

Type to search this documentation.

Get spans by project_name or project_id and optionally by trace_id and/or type

GET/v1/private/spansGet spans by project_name or project_id and optionally by trace_id and/or type

Get spans by project_name or project_id and optionally by trace_id and/or type

Parameters

pageinteger · int32query

default 1 · minimum 1

sizeinteger · int32query

default 10 · minimum 1

project_namestringquery
project_idstring · uuidquery
trace_idstring · uuidquery
typestringquery

one of "general", "tool", "llm", "guardrail"

one of "general", "tool", "llm", "guardrail"

filtersstringquery
truncatebooleanquery

Truncate input, output and metadata to slim payloads

default false

strip_attachmentsbooleanquery

If true, returns attachment references like [file.png]; if false, downloads and reinjects stripped attachments

default false

sortingstringquery
excludestringquery
searchstringquery

Full-text search across span fields

from_timestring · date-timequery

Filter spans created from this time (ISO-8601 format).

to_timestring · date-timequery

Filter spans created up to this time (ISO-8601 format). If not provided, defaults to current time. Must be after 'from_time'.

Responses

200Spans resourceapplication/json
objectSpanPage_Public
contentarray of object
Show child attributes
Show array items
commentsarray of object
Show child attributes
Show array items
created_atstring · date-time
created_bystring
idstring · uuid
last_updated_atstring · date-time
last_updated_bystring
source_queue_idstring · uuid
textstringrequired

minLength 1

created_atstring · date-time
created_bystring
durationnumber · double

Duration in milliseconds as a decimal number to support sub-millisecond precision

end_timestring · date-time
environmentstring

maxLength 150 · minLength 0

error_infoobject
Show child attributes
exception_typestringrequired

minLength 1

messagestring
tracebackstringrequired

minLength 1

feedback_scoresarray of object
Show child attributes
Show array items

Aggregated feedback scores from all spans in this trace, averaged by score name

category_namestring
created_atstring · date-time
created_bystring
last_updated_atstring · date-time
last_updated_bystring
namestringrequired

minLength 1

reasonstring
sourcestringrequired

one of "ui", "sdk", "online_scoring"

source_queue_idstring · uuid
valuenumberrequired

maximum 1000000000 · minimum -1000000000

value_by_authorobject
idstring · uuid
inputobject
Show child attributes
anyOf · 3 options
Option 1object
Option 2array of object
Option 3string
last_updated_atstring · date-time
last_updated_bystring
metadataobjectJsonListString_Public ↑
modelstring
namestring
outputobjectJsonListString_Public ↑
parent_span_idstring · uuid
project_idstring · uuid
project_namestring

If null, the default project is used

pattern (?s)^\s*(\S.*\S|\S)\s*$

providerstring
sourcestring

one of "sdk", "experiment", "playground", "optimization", "evaluator"

start_timestring · date-timerequired
tagsarray of string

uniqueItems true

Show child attributes

uniqueItems true

total_estimated_costnumber

minimum 0

total_estimated_cost_versionstring
trace_idstring · uuid
ttftnumber · double

Time to first token in milliseconds

typestring

one of "general", "tool", "llm", "guardrail"

usageobject
pageinteger · int32
sizeinteger · int32
sortableByarray of string
Show child attributes
totalinteger · int64
Example response
{
  "content": [
    {
      "comments": [
        {
          "created_at": "2026-06-09T00:00:00Z",
          "created_by": "string",
          "id": "00000000-0000-0000-0000-000000000000",
          "last_updated_at": "2026-06-09T00:00:00Z",
          "last_updated_by": "string",
          "source_queue_id": "00000000-0000-0000-0000-000000000000",
          "text": "string"
        }
      ],
      "created_at": "2026-06-09T00:00:00Z",
      "created_by": "string",
      "duration": 0,
      "end_time": "2026-06-09T00:00:00Z",
      "environment": "string",
      "error_info": {
        "exception_type": "string",
        "message": "string",
        "traceback": "string"
      },
      "feedback_scores": [
        {
          "category_name": "string",
          "created_at": "2026-06-09T00:00:00Z",
          "created_by": "string",
          "last_updated_at": "2026-06-09T00:00:00Z",
          "last_updated_by": "string",
          "name": "string",
          "reason": "string",
          "source": "online_scoring",
          "source_queue_id": "00000000-0000-0000-0000-000000000000",
          "value": 0,
          "value_by_author": {
            "additionalProp1": {
              "author": "string",
              "category_name": "string",
              "last_updated_at": "2026-06-09T00:00:00Z",
              "reason": "string",
              "source": "online_scoring",
              "source_queue_id": "string",
              "span_id": "string",
              "span_type": "string",
              "value": 0
            }
          }
        }
      ],
      "id": "00000000-0000-0000-0000-000000000000",
      "input": [
        {}
      ],
      "last_updated_at": "2026-06-09T00:00:00Z",
      "last_updated_by": "string",
      "metadata": [
        {}
      ],
      "model": "string",
      "name": "string",
      "output": [
        {}
      ],
      "parent_span_id": "00000000-0000-0000-0000-000000000000",
      "project_id": "00000000-0000-0000-0000-000000000000",
      "project_name": "string",
      "provider": "string",
      "source": "evaluator",
      "start_time": "2026-06-09T00:00:00Z",
      "tags": [
        "string"
      ],
      "total_estimated_cost": 0,
      "total_estimated_cost_version": "string",
      "trace_id": "00000000-0000-0000-0000-000000000000",
      "ttft": 0,
      "type": "general",
      "usage": {
        "additionalProp1": 0
      }
    }
  ],
  "page": 0,
  "size": 0,
  "sortableBy": [
    "string"
  ],
  "total": 0
}
Documentation menu