curl --request POST \
--url https://api.example.com/traces/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"filter": {},
"group_by": "run",
"page": 1,
"limit": 20
}
'import requests
url = "https://api.example.com/traces/search"
payload = {
"filter": {},
"group_by": "run",
"page": 1,
"limit": 20
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({filter: {}, group_by: 'run', page: 1, limit: 20})
};
fetch('https://api.example.com/traces/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/traces/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'filter' => [
],
'group_by' => 'run',
'page' => 1,
'limit' => 20
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/traces/search"
payload := strings.NewReader("{\n \"filter\": {},\n \"group_by\": \"run\",\n \"page\": 1,\n \"limit\": 20\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/traces/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"filter\": {},\n \"group_by\": \"run\",\n \"page\": 1,\n \"limit\": 20\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/traces/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"filter\": {},\n \"group_by\": \"run\",\n \"page\": 1,\n \"limit\": 20\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"trace_id": "<string>",
"name": "<string>",
"status": "<string>",
"duration": "<string>",
"start_time": "2023-11-07T05:31:56Z",
"end_time": "2023-11-07T05:31:56Z",
"total_spans": 123,
"error_count": 123,
"created_at": "2023-11-07T05:31:56Z",
"tree": [
{
"id": "<string>",
"name": "<string>",
"type": "<string>",
"duration": "<string>",
"start_time": "2023-11-07T05:31:56Z",
"end_time": "2023-11-07T05:31:56Z",
"status": "<string>",
"input": "<string>",
"output": "<string>",
"error": "<string>",
"spans": [
"<unknown>"
],
"step_type": "<string>",
"metadata": {},
"extra_data": {}
}
],
"input": "<string>",
"output": "<string>",
"error": "<string>",
"run_id": "<string>",
"session_id": "<string>",
"user_id": "<string>",
"agent_id": "<string>",
"team_id": "<string>",
"workflow_id": "<string>"
}
],
"meta": {
"page": 0,
"limit": 20,
"total_pages": 0,
"total_count": 0,
"search_time_ms": 0
}
}{
"detail": "Bad request",
"error_code": "BAD_REQUEST"
}{
"detail": "Unauthenticated access",
"error_code": "UNAUTHENTICATED"
}{
"detail": "Not found",
"error_code": "NOT_FOUND"
}{
"detail": "Validation error",
"error_code": "VALIDATION_ERROR"
}{
"detail": "Internal server error",
"error_code": "INTERNAL_SERVER_ERROR"
}Search Traces with Advanced Filters
Search traces using the FilterExpr DSL for complex, composable queries.
Group By Mode:
run(default): ReturnsPaginatedResponse[TraceDetail]with full span treessession: ReturnsPaginatedResponse[TraceSessionStats]with aggregated session stats
Supported Operators:
- Comparison:
EQ,NEQ,GT,GTE,LT,LTE - Inclusion:
IN - String matching:
CONTAINS(case-insensitive substring),STARTSWITH(prefix) - Logical:
AND,OR,NOT
Filterable Fields: trace_id, name, status, start_time, end_time, duration_ms, run_id, session_id, user_id, agent_id, team_id, workflow_id, created_at
Example Request Body (runs):
{
"filter": {"op": "EQ", "key": "status", "value": "OK"},
"group_by": "run",
"page": 1,
"limit": 20
}
Example Request Body (sessions):
{
"filter": {"op": "CONTAINS", "key": "agent_id", "value": "stock"},
"group_by": "session",
"page": 1,
"limit": 20
}
curl --request POST \
--url https://api.example.com/traces/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"filter": {},
"group_by": "run",
"page": 1,
"limit": 20
}
'import requests
url = "https://api.example.com/traces/search"
payload = {
"filter": {},
"group_by": "run",
"page": 1,
"limit": 20
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({filter: {}, group_by: 'run', page: 1, limit: 20})
};
fetch('https://api.example.com/traces/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/traces/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'filter' => [
],
'group_by' => 'run',
'page' => 1,
'limit' => 20
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/traces/search"
payload := strings.NewReader("{\n \"filter\": {},\n \"group_by\": \"run\",\n \"page\": 1,\n \"limit\": 20\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/traces/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"filter\": {},\n \"group_by\": \"run\",\n \"page\": 1,\n \"limit\": 20\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/traces/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"filter\": {},\n \"group_by\": \"run\",\n \"page\": 1,\n \"limit\": 20\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"trace_id": "<string>",
"name": "<string>",
"status": "<string>",
"duration": "<string>",
"start_time": "2023-11-07T05:31:56Z",
"end_time": "2023-11-07T05:31:56Z",
"total_spans": 123,
"error_count": 123,
"created_at": "2023-11-07T05:31:56Z",
"tree": [
{
"id": "<string>",
"name": "<string>",
"type": "<string>",
"duration": "<string>",
"start_time": "2023-11-07T05:31:56Z",
"end_time": "2023-11-07T05:31:56Z",
"status": "<string>",
"input": "<string>",
"output": "<string>",
"error": "<string>",
"spans": [
"<unknown>"
],
"step_type": "<string>",
"metadata": {},
"extra_data": {}
}
],
"input": "<string>",
"output": "<string>",
"error": "<string>",
"run_id": "<string>",
"session_id": "<string>",
"user_id": "<string>",
"agent_id": "<string>",
"team_id": "<string>",
"workflow_id": "<string>"
}
],
"meta": {
"page": 0,
"limit": 20,
"total_pages": 0,
"total_count": 0,
"search_time_ms": 0
}
}{
"detail": "Bad request",
"error_code": "BAD_REQUEST"
}{
"detail": "Unauthenticated access",
"error_code": "UNAUTHENTICATED"
}{
"detail": "Not found",
"error_code": "NOT_FOUND"
}{
"detail": "Validation error",
"error_code": "VALIDATION_ERROR"
}{
"detail": "Internal server error",
"error_code": "INTERNAL_SERVER_ERROR"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Database ID to query traces from
Body
Request body for POST /traces/search with advanced filtering.
The filter field accepts a FilterExpr DSL dict supporting composable queries with AND/OR/NOT logic and operators like EQ, NEQ, GT, GTE, LT, LTE, IN, CONTAINS, STARTSWITH.
Example for run grouping (default): { "filter": { "op": "AND", "conditions": [ {"op": "EQ", "key": "status", "value": "OK"}, {"op": "CONTAINS", "key": "user_id", "value": "admin"} ] }, "group_by": "run", "page": 1, "limit": 20 }
Example for session grouping: { "filter": {"op": "EQ", "key": "agent_id", "value": "my-agent"}, "group_by": "session", "page": 1, "limit": 20 }
FilterExpr DSL as JSON dict. Supports operators: EQ, NEQ, GT, GTE, LT, LTE, IN, CONTAINS, STARTSWITH, AND, OR, NOT.
Grouping mode: 'run' returns individual TraceDetail, 'session' returns aggregated TraceSessionStats.
run, session Page number (1-indexed)
x >= 1Number of traces per page (max 100)
1 <= x <= 100Was this page helpful?