Search spans | Opik Documentation

POST/v1/private/spans/searchSearch spans

Search spans

Request body

application/json

objectSpanSearchStreamRequest_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 spans created from this time (ISO-8601 format).

last_retrieved_idstring · uuid

limitinteger · int32

Max number of spans to be streamed

default 500 · maximum 2000 · minimum 1

project_idstring · uuid

project_namestring

to_timestring · date-time

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

trace_idstring · uuid

truncateboolean

Truncate image included in either input, output or metadata

default true

typestring

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

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",
  "to_time": "2026-06-09T00:00:00Z",
  "trace_id": "00000000-0000-0000-0000-000000000000",
  "truncate": true,
  "type": "general"
}

Responses

array of string

maxItems 2000

Show array items

anyOf · 2 options

Option 1objectSpan_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

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

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"
}

Examples

curl -X POST 'http://localhost:5173/api/v1/private/spans/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","to_time":"2026-06-09T00:00:00Z","trace_id":"00000000-0000-0000-0000-000000000000","truncate":true,"type":"general"}'

const response = await fetch('http://localhost:5173/api/v1/private/spans/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","to_time":"2026-06-09T00:00:00Z","trace_id":"00000000-0000-0000-0000-000000000000","truncate":true,"type":"general"}),
});
const data = await response.json();

const response = await fetch('http://localhost:5173/api/v1/private/spans/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\",\"to_time\":\"2026-06-09T00:00:00Z\",\"trace_id\":\"00000000-0000-0000-0000-000000000000\",\"truncate\":true,\"type\":\"general\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "http://localhost:5173/api/v1/private/spans/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","to_time":"2026-06-09T00:00:00Z","trace_id":"00000000-0000-0000-0000-000000000000","truncate":true,"type":"general"}',
)
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","to_time":"2026-06-09T00:00:00Z","trace_id":"00000000-0000-0000-0000-000000000000","truncate":true,"type":"general"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "http://localhost:5173/api/v1/private/spans/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/spans/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\",\"to_time\":\"2026-06-09T00:00:00Z\",\"trace_id\":\"00000000-0000-0000-0000-000000000000\",\"truncate\":true,\"type\":\"general\"}");
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/spans/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\",\"to_time\":\"2026-06-09T00:00:00Z\",\"trace_id\":\"00000000-0000-0000-0000-000000000000\",\"truncate\":true,\"type\":\"general\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("http://localhost:5173/api/v1/private/spans/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\",\"to_time\":\"2026-06-09T00:00:00Z\",\"trace_id\":\"00000000-0000-0000-0000-000000000000\",\"truncate\":true,\"type\":\"general\"}"
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/spans/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\",\"to_time\":\"2026-06-09T00:00:00Z\",\"trace_id\":\"00000000-0000-0000-0000-000000000000\",\"truncate\":true,\"type\":\"general\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

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

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