curl --request GET \
--url https://api.example.com/traces \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/traces"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/traces', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/traces"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/traces")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/traces")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"trace_id": "a1b2c3d4",
"name": "Stock_Price_Agent.run",
"status": "OK",
"duration": "1.2s",
"start_time": "2025-11-19T10:30:00.000000+00:00",
"total_spans": 4,
"error_count": 0,
"input": "What is the stock price of NVDA?",
"run_id": "run123",
"session_id": "session456",
"user_id": "user789",
"agent_id": "agent_stock",
"created_at": "2025-11-19T10:30:00+00:00"
}
],
"meta": {
"page": 1,
"limit": 20,
"total_pages": 5,
"total_count": 95
}
}{
"detail": "Bad request",
"error_code": "BAD_REQUEST"
}{
"detail": "Unauthenticated access",
"error_code": "UNAUTHENTICATED"
}{
"detail": "Insufficient permissions"
}{
"detail": "Not found",
"error_code": "NOT_FOUND"
}{
"detail": "Validation error",
"error_code": "VALIDATION_ERROR"
}{
"detail": "Internal server error",
"error_code": "INTERNAL_SERVER_ERROR"
}List Traces
Retrieve a paginated list of execution traces with optional filtering.
Traces provide observability into:
- Agent execution flows
- Model invocations and token usage
- Tool calls and their results
- Errors and performance bottlenecks
Filtering Options:
- By run, session, user, or agent ID
- By status (OK, ERROR)
- By time range
Pagination:
- Use
page(1-indexed) andlimitparameters - Response includes pagination metadata (total_pages, total_count, etc.)
Response Format:
Returns summary information for each trace. Use GET /traces/{trace_id} for detailed hierarchy.
curl --request GET \
--url https://api.example.com/traces \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/traces"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/traces', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/traces"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/traces")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/traces")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"trace_id": "a1b2c3d4",
"name": "Stock_Price_Agent.run",
"status": "OK",
"duration": "1.2s",
"start_time": "2025-11-19T10:30:00.000000+00:00",
"total_spans": 4,
"error_count": 0,
"input": "What is the stock price of NVDA?",
"run_id": "run123",
"session_id": "session456",
"user_id": "user789",
"agent_id": "agent_stock",
"created_at": "2025-11-19T10:30:00+00:00"
}
],
"meta": {
"page": 1,
"limit": 20,
"total_pages": 5,
"total_count": 95
}
}{
"detail": "Bad request",
"error_code": "BAD_REQUEST"
}{
"detail": "Unauthenticated access",
"error_code": "UNAUTHENTICATED"
}{
"detail": "Insufficient permissions"
}{
"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
Filter by run ID
Filter by session ID
Filter by user ID
Filter by agent ID
Filter by team ID
Filter by workflow ID
Filter by status (OK, ERROR)
Filter traces starting after this time (ISO 8601 format with timezone, e.g., '2025-11-19T10:00:00Z' or '2025-11-19T15:30:00+05:30'). Times are converted to UTC for comparison.
Filter traces ending before this time (ISO 8601 format with timezone, e.g., '2025-11-19T11:00:00Z' or '2025-11-19T16:30:00+05:30'). Times are converted to UTC for comparison.
1-based page number. Agno 2.7.4 also accepts 0 at request validation, but the pagination implementation is 1-based. Use 1 or greater.
x >= 0Number of traces per page
x >= 1Database ID to query traces from
Was this page helpful?