Skip to main content
Opik Documentation

Search documentation

Type to search this documentation.

Get traces by project_name or project_id

GET/v1/private/tracesGet traces by project_name or project_id

Get traces by project_name or project_id

Parameters

pageinteger · int32query

default 1 · minimum 1

sizeinteger · int32query

default 10 · minimum 1

project_namestringquery
project_idstring · uuidquery
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 trace fields

from_timestring · date-timequery

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

to_timestring · date-timequery

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

annotation_queue_idstring · uuidquery

Filter traces belonging to this annotation queue and scope feedback scores/comments to it

Responses

200Trace resourceapplication/json
objectTracePage_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

experimentobject

Experiment reference with ID, name, dataset ID, and dataset item ID

Show child attributes
dataset_idstring · uuidrequired

Dataset ID

dataset_item_idstring · uuidrequired

Dataset Item ID

idstring · uuidrequired

Experiment ID

namestringrequired

Experiment name

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
guardrails_validationsarray of object
Show child attributes
Show array items
checksarray of object
Show child attributes
Show array items
namestring

one of "TOPIC", "PII", "LLM_JUDGE", "PROMPT_INJECTION", "CUSTOM_CLASSIFIER"

resultstring

one of "passed", "failed"

span_idstring · uuid
has_tool_spansboolean
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
llm_span_countinteger · int32
metadataobjectJsonListString_Public ↑
namestring
outputobjectJsonListString_Public ↑
project_idstring · uuid
providersarray of string

List of unique provider names from all spans in this trace, sorted alphabetically

Show child attributes
sourcestring

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

span_countinteger · int32
span_feedback_scoresarray of object

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

Show child attributes

Items: FeedbackScore_Public ↑

start_timestring · date-timerequired
tagsarray of string

uniqueItems true

Show child attributes

uniqueItems true

thread_idstring
total_estimated_costnumber
ttftnumber · double

Time to first token in milliseconds

usageobject
visibility_modestring

one of "default", "hidden"

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"
      },
      "experiment": {
        "dataset_id": "00000000-0000-0000-0000-000000000000",
        "dataset_item_id": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "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
            }
          }
        }
      ],
      "guardrails_validations": [
        {
          "checks": [
            {
              "name": "CUSTOM_CLASSIFIER",
              "result": "failed"
            }
          ],
          "span_id": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "has_tool_spans": true,
      "id": "00000000-0000-0000-0000-000000000000",
      "input": [
        {}
      ],
      "last_updated_at": "2026-06-09T00:00:00Z",
      "last_updated_by": "string",
      "llm_span_count": 0,
      "metadata": [
        {}
      ],
      "name": "string",
      "output": [
        {}
      ],
      "project_id": "00000000-0000-0000-0000-000000000000",
      "providers": [
        "string"
      ],
      "source": "evaluator",
      "span_count": 0,
      "span_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"
            }
          }
        }
      ],
      "start_time": "2026-06-09T00:00:00Z"
    }
  ]
}
Documentation menu