Search traces | Opik Documentation

POST/v1/private/traces/searchSearch traces

Search traces

Request body

application/json

objectTraceSearchStreamRequest_Public

excludearray of string

Fields to exclude from the response

uniqueItems true

Show child attributes

uniqueItems true

filtersarray of object

Show child attributes

Show array items

fieldstring

keystring

operatorstring

one of "contains", "not_contains", "starts_with", "ends_with", "=", "!=", ">", ">=", "<", "<=", "is_empty", "is_not_empty", "in", "not_in"

valuestring

from_timestring · date-time

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

last_retrieved_idstring · uuid

limitinteger · int32

Max number of traces to be streamed

default 500 · maximum 2000 · minimum 1

project_idstring · uuid

project_namestring

strip_attachmentsboolean

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

default false

to_timestring · date-time

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

truncateboolean

Truncate input, output and metadata to slim payloads

default true

Example request

{
  "exclude": [
    "comments"
  ],
  "filters": [
    {
      "field": "string",
      "key": "string",
      "operator": "!=",
      "value": "string"
    }
  ],
  "from_time": "2026-06-09T00:00:00Z",
  "last_retrieved_id": "00000000-0000-0000-0000-000000000000",
  "limit": 500,
  "project_id": "00000000-0000-0000-0000-000000000000",
  "project_name": "string",
  "strip_attachments": false,
  "to_time": "2026-06-09T00:00:00Z",
  "truncate": true
}

Responses

array of string

maxItems 2000

Show array items

anyOf · 2 options

Option 1objectTrace_Public

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"

Option 2objectErrorMessage_Public

codeinteger · int32

detailsstring

messagestring

Example response

[
  {
    "code": 0,
    "details": "string",
    "message": "string"
  }
]

objectErrorMessage_Public

codeinteger · int32

detailsstring

messagestring

Example response

{
  "code": 0,
  "details": "string",
  "message": "string"
}

objectErrorMessage_Public

codeinteger · int32

detailsstring

messagestring

Example response

{
  "code": 0,
  "details": "string",
  "message": "string"
}

Examples

curl -X POST 'http://localhost:5173/api/v1/private/traces/search' \
  -H 'Content-Type: application/json' \
  -d '{"exclude":["comments"],"filters":[{"field":"string","key":"string","operator":"!=","value":"string"}],"from_time":"2026-06-09T00:00:00Z","last_retrieved_id":"00000000-0000-0000-0000-000000000000","limit":500,"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string","strip_attachments":false,"to_time":"2026-06-09T00:00:00Z","truncate":true}'

const response = await fetch('http://localhost:5173/api/v1/private/traces/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"exclude":["comments"],"filters":[{"field":"string","key":"string","operator":"!=","value":"string"}],"from_time":"2026-06-09T00:00:00Z","last_retrieved_id":"00000000-0000-0000-0000-000000000000","limit":500,"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string","strip_attachments":false,"to_time":"2026-06-09T00:00:00Z","truncate":true}),
});
const data = await response.json();

const response = await fetch('http://localhost:5173/api/v1/private/traces/search', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"exclude\":[\"comments\"],\"filters\":[{\"field\":\"string\",\"key\":\"string\",\"operator\":\"!=\",\"value\":\"string\"}],\"from_time\":\"2026-06-09T00:00:00Z\",\"last_retrieved_id\":\"00000000-0000-0000-0000-000000000000\",\"limit\":500,\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\",\"strip_attachments\":false,\"to_time\":\"2026-06-09T00:00:00Z\",\"truncate\":true}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "http://localhost:5173/api/v1/private/traces/search",
    headers={"Content-Type": "application/json"},
    data='{"exclude":["comments"],"filters":[{"field":"string","key":"string","operator":"!=","value":"string"}],"from_time":"2026-06-09T00:00:00Z","last_retrieved_id":"00000000-0000-0000-0000-000000000000","limit":500,"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string","strip_attachments":false,"to_time":"2026-06-09T00:00:00Z","truncate":true}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"exclude":["comments"],"filters":[{"field":"string","key":"string","operator":"!=","value":"string"}],"from_time":"2026-06-09T00:00:00Z","last_retrieved_id":"00000000-0000-0000-0000-000000000000","limit":500,"project_id":"00000000-0000-0000-0000-000000000000","project_name":"string","strip_attachments":false,"to_time":"2026-06-09T00:00:00Z","truncate":true}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "http://localhost:5173/api/v1/private/traces/search", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("http://localhost:5173/api/v1/private/traces/search");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"exclude\":[\"comments\"],\"filters\":[{\"field\":\"string\",\"key\":\"string\",\"operator\":\"!=\",\"value\":\"string\"}],\"from_time\":\"2026-06-09T00:00:00Z\",\"last_retrieved_id\":\"00000000-0000-0000-0000-000000000000\",\"limit\":500,\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\",\"strip_attachments\":false,\"to_time\":\"2026-06-09T00:00:00Z\",\"truncate\":true}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("http://localhost:5173/api/v1/private/traces/search"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"exclude\":[\"comments\"],\"filters\":[{\"field\":\"string\",\"key\":\"string\",\"operator\":\"!=\",\"value\":\"string\"}],\"from_time\":\"2026-06-09T00:00:00Z\",\"last_retrieved_id\":\"00000000-0000-0000-0000-000000000000\",\"limit\":500,\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\",\"strip_attachments\":false,\"to_time\":\"2026-06-09T00:00:00Z\",\"truncate\":true}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("http://localhost:5173/api/v1/private/traces/search")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"exclude\":[\"comments\"],\"filters\":[{\"field\":\"string\",\"key\":\"string\",\"operator\":\"!=\",\"value\":\"string\"}],\"from_time\":\"2026-06-09T00:00:00Z\",\"last_retrieved_id\":\"00000000-0000-0000-0000-000000000000\",\"limit\":500,\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\",\"strip_attachments\":false,\"to_time\":\"2026-06-09T00:00:00Z\",\"truncate\":true}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "http://localhost:5173/api/v1/private/traces/search");
request.Content = new StringContent("{\"exclude\":[\"comments\"],\"filters\":[{\"field\":\"string\",\"key\":\"string\",\"operator\":\"!=\",\"value\":\"string\"}],\"from_time\":\"2026-06-09T00:00:00Z\",\"last_retrieved_id\":\"00000000-0000-0000-0000-000000000000\",\"limit\":500,\"project_id\":\"00000000-0000-0000-0000-000000000000\",\"project_name\":\"string\",\"strip_attachments\":false,\"to_time\":\"2026-06-09T00:00:00Z\",\"truncate\":true}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

[
  {
    "code": 0,
    "details": "string",
    "message": "string"
  }
]

{
  "code": 0,
  "details": "string",
  "message": "string"
}

{
  "code": 0,
  "details": "string",
  "message": "string"
}