Get filtered spans data with detailed attributes
curl --request POST \
--url https://{controlPlaneURL}/api/svc/v1/spans/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"startTime": "<string>",
"endTime": "<string>",
"traceIds": [
"traceid1",
"traceid2"
],
"spanIds": [
"spanId1",
"spanId2"
],
"parentSpanIds": [
"",
"parentSpanId1",
"parentSpanId2"
],
"createdBySubjectTypes": [
"user",
"virtualaccount"
],
"createdBySubjectSlugs": [
"user@example.com",
"service-account"
],
"applicationNames": [
"tfy-llm-gateway",
"order-service"
],
"limit": 200,
"sortDirection": "desc",
"pageToken": "<string>",
"tracingProjectFqn": "<string>",
"dataRoutingDestination": "<string>",
"filters": [
{
"value": "<string>"
}
],
"includeFeedbacks": false
}
'import requests
url = "https://{controlPlaneURL}/api/svc/v1/spans/query"
payload = {
"startTime": "<string>",
"endTime": "<string>",
"traceIds": ["traceid1", "traceid2"],
"spanIds": ["spanId1", "spanId2"],
"parentSpanIds": ["", "parentSpanId1", "parentSpanId2"],
"createdBySubjectTypes": ["user", "virtualaccount"],
"createdBySubjectSlugs": ["user@example.com", "service-account"],
"applicationNames": ["tfy-llm-gateway", "order-service"],
"limit": 200,
"sortDirection": "desc",
"pageToken": "<string>",
"tracingProjectFqn": "<string>",
"dataRoutingDestination": "<string>",
"filters": [{ "value": "<string>" }],
"includeFeedbacks": False
}
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({
startTime: '<string>',
endTime: '<string>',
traceIds: ['traceid1', 'traceid2'],
spanIds: ['spanId1', 'spanId2'],
parentSpanIds: ['', 'parentSpanId1', 'parentSpanId2'],
createdBySubjectTypes: ['user', 'virtualaccount'],
createdBySubjectSlugs: ['user@example.com', 'service-account'],
applicationNames: ['tfy-llm-gateway', 'order-service'],
limit: 200,
sortDirection: 'desc',
pageToken: '<string>',
tracingProjectFqn: '<string>',
dataRoutingDestination: '<string>',
filters: [{value: '<string>'}],
includeFeedbacks: false
})
};
fetch('https://{controlPlaneURL}/api/svc/v1/spans/query', 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://{controlPlaneURL}/api/svc/v1/spans/query",
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([
'startTime' => '<string>',
'endTime' => '<string>',
'traceIds' => [
'traceid1',
'traceid2'
],
'spanIds' => [
'spanId1',
'spanId2'
],
'parentSpanIds' => [
'',
'parentSpanId1',
'parentSpanId2'
],
'createdBySubjectTypes' => [
'user',
'virtualaccount'
],
'createdBySubjectSlugs' => [
'user@example.com',
'service-account'
],
'applicationNames' => [
'tfy-llm-gateway',
'order-service'
],
'limit' => 200,
'sortDirection' => 'desc',
'pageToken' => '<string>',
'tracingProjectFqn' => '<string>',
'dataRoutingDestination' => '<string>',
'filters' => [
[
'value' => '<string>'
]
],
'includeFeedbacks' => false
]),
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://{controlPlaneURL}/api/svc/v1/spans/query"
payload := strings.NewReader("{\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\",\n \"traceIds\": [\n \"traceid1\",\n \"traceid2\"\n ],\n \"spanIds\": [\n \"spanId1\",\n \"spanId2\"\n ],\n \"parentSpanIds\": [\n \"\",\n \"parentSpanId1\",\n \"parentSpanId2\"\n ],\n \"createdBySubjectTypes\": [\n \"user\",\n \"virtualaccount\"\n ],\n \"createdBySubjectSlugs\": [\n \"user@example.com\",\n \"service-account\"\n ],\n \"applicationNames\": [\n \"tfy-llm-gateway\",\n \"order-service\"\n ],\n \"limit\": 200,\n \"sortDirection\": \"desc\",\n \"pageToken\": \"<string>\",\n \"tracingProjectFqn\": \"<string>\",\n \"dataRoutingDestination\": \"<string>\",\n \"filters\": [\n {\n \"value\": \"<string>\"\n }\n ],\n \"includeFeedbacks\": false\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://{controlPlaneURL}/api/svc/v1/spans/query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\",\n \"traceIds\": [\n \"traceid1\",\n \"traceid2\"\n ],\n \"spanIds\": [\n \"spanId1\",\n \"spanId2\"\n ],\n \"parentSpanIds\": [\n \"\",\n \"parentSpanId1\",\n \"parentSpanId2\"\n ],\n \"createdBySubjectTypes\": [\n \"user\",\n \"virtualaccount\"\n ],\n \"createdBySubjectSlugs\": [\n \"user@example.com\",\n \"service-account\"\n ],\n \"applicationNames\": [\n \"tfy-llm-gateway\",\n \"order-service\"\n ],\n \"limit\": 200,\n \"sortDirection\": \"desc\",\n \"pageToken\": \"<string>\",\n \"tracingProjectFqn\": \"<string>\",\n \"dataRoutingDestination\": \"<string>\",\n \"filters\": [\n {\n \"value\": \"<string>\"\n }\n ],\n \"includeFeedbacks\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{controlPlaneURL}/api/svc/v1/spans/query")
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 \"startTime\": \"<string>\",\n \"endTime\": \"<string>\",\n \"traceIds\": [\n \"traceid1\",\n \"traceid2\"\n ],\n \"spanIds\": [\n \"spanId1\",\n \"spanId2\"\n ],\n \"parentSpanIds\": [\n \"\",\n \"parentSpanId1\",\n \"parentSpanId2\"\n ],\n \"createdBySubjectTypes\": [\n \"user\",\n \"virtualaccount\"\n ],\n \"createdBySubjectSlugs\": [\n \"user@example.com\",\n \"service-account\"\n ],\n \"applicationNames\": [\n \"tfy-llm-gateway\",\n \"order-service\"\n ],\n \"limit\": 200,\n \"sortDirection\": \"desc\",\n \"pageToken\": \"<string>\",\n \"tracingProjectFqn\": \"<string>\",\n \"dataRoutingDestination\": \"<string>\",\n \"filters\": [\n {\n \"value\": \"<string>\"\n }\n ],\n \"includeFeedbacks\": false\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"spanId": "<string>",
"traceId": "<string>",
"parentSpanId": "<string>",
"serviceName": "<string>",
"spanName": "<string>",
"spanKind": "<string>",
"scopeName": "<string>",
"scopeVersion": "<string>",
"timestamp": "<string>",
"durationNs": 123,
"statusCode": "<string>",
"statusMessage": "<string>",
"spanAttributes": {},
"events": [
{}
],
"createdBySubject": {
"subjectId": "<string>",
"subjectSlug": "<string>",
"subjectDisplayName": "<string>",
"subjectPatName": "<string>",
"subjectControllerName": "<string>",
"subjectExternalIdentitySlug": "<string>"
},
"feedbacks": [
"<array>"
]
}
],
"pagination": {
"limit": 10,
"nextPageToken": "<string>",
"previousPageToken": "<string>"
}
}Traces
Get filtered spans data with detailed attributes
POST
/
api
/
svc
/
v1
/
spans
/
query
Get filtered spans data with detailed attributes
curl --request POST \
--url https://{controlPlaneURL}/api/svc/v1/spans/query \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"startTime": "<string>",
"endTime": "<string>",
"traceIds": [
"traceid1",
"traceid2"
],
"spanIds": [
"spanId1",
"spanId2"
],
"parentSpanIds": [
"",
"parentSpanId1",
"parentSpanId2"
],
"createdBySubjectTypes": [
"user",
"virtualaccount"
],
"createdBySubjectSlugs": [
"user@example.com",
"service-account"
],
"applicationNames": [
"tfy-llm-gateway",
"order-service"
],
"limit": 200,
"sortDirection": "desc",
"pageToken": "<string>",
"tracingProjectFqn": "<string>",
"dataRoutingDestination": "<string>",
"filters": [
{
"value": "<string>"
}
],
"includeFeedbacks": false
}
'import requests
url = "https://{controlPlaneURL}/api/svc/v1/spans/query"
payload = {
"startTime": "<string>",
"endTime": "<string>",
"traceIds": ["traceid1", "traceid2"],
"spanIds": ["spanId1", "spanId2"],
"parentSpanIds": ["", "parentSpanId1", "parentSpanId2"],
"createdBySubjectTypes": ["user", "virtualaccount"],
"createdBySubjectSlugs": ["user@example.com", "service-account"],
"applicationNames": ["tfy-llm-gateway", "order-service"],
"limit": 200,
"sortDirection": "desc",
"pageToken": "<string>",
"tracingProjectFqn": "<string>",
"dataRoutingDestination": "<string>",
"filters": [{ "value": "<string>" }],
"includeFeedbacks": False
}
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({
startTime: '<string>',
endTime: '<string>',
traceIds: ['traceid1', 'traceid2'],
spanIds: ['spanId1', 'spanId2'],
parentSpanIds: ['', 'parentSpanId1', 'parentSpanId2'],
createdBySubjectTypes: ['user', 'virtualaccount'],
createdBySubjectSlugs: ['user@example.com', 'service-account'],
applicationNames: ['tfy-llm-gateway', 'order-service'],
limit: 200,
sortDirection: 'desc',
pageToken: '<string>',
tracingProjectFqn: '<string>',
dataRoutingDestination: '<string>',
filters: [{value: '<string>'}],
includeFeedbacks: false
})
};
fetch('https://{controlPlaneURL}/api/svc/v1/spans/query', 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://{controlPlaneURL}/api/svc/v1/spans/query",
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([
'startTime' => '<string>',
'endTime' => '<string>',
'traceIds' => [
'traceid1',
'traceid2'
],
'spanIds' => [
'spanId1',
'spanId2'
],
'parentSpanIds' => [
'',
'parentSpanId1',
'parentSpanId2'
],
'createdBySubjectTypes' => [
'user',
'virtualaccount'
],
'createdBySubjectSlugs' => [
'user@example.com',
'service-account'
],
'applicationNames' => [
'tfy-llm-gateway',
'order-service'
],
'limit' => 200,
'sortDirection' => 'desc',
'pageToken' => '<string>',
'tracingProjectFqn' => '<string>',
'dataRoutingDestination' => '<string>',
'filters' => [
[
'value' => '<string>'
]
],
'includeFeedbacks' => false
]),
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://{controlPlaneURL}/api/svc/v1/spans/query"
payload := strings.NewReader("{\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\",\n \"traceIds\": [\n \"traceid1\",\n \"traceid2\"\n ],\n \"spanIds\": [\n \"spanId1\",\n \"spanId2\"\n ],\n \"parentSpanIds\": [\n \"\",\n \"parentSpanId1\",\n \"parentSpanId2\"\n ],\n \"createdBySubjectTypes\": [\n \"user\",\n \"virtualaccount\"\n ],\n \"createdBySubjectSlugs\": [\n \"user@example.com\",\n \"service-account\"\n ],\n \"applicationNames\": [\n \"tfy-llm-gateway\",\n \"order-service\"\n ],\n \"limit\": 200,\n \"sortDirection\": \"desc\",\n \"pageToken\": \"<string>\",\n \"tracingProjectFqn\": \"<string>\",\n \"dataRoutingDestination\": \"<string>\",\n \"filters\": [\n {\n \"value\": \"<string>\"\n }\n ],\n \"includeFeedbacks\": false\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://{controlPlaneURL}/api/svc/v1/spans/query")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"startTime\": \"<string>\",\n \"endTime\": \"<string>\",\n \"traceIds\": [\n \"traceid1\",\n \"traceid2\"\n ],\n \"spanIds\": [\n \"spanId1\",\n \"spanId2\"\n ],\n \"parentSpanIds\": [\n \"\",\n \"parentSpanId1\",\n \"parentSpanId2\"\n ],\n \"createdBySubjectTypes\": [\n \"user\",\n \"virtualaccount\"\n ],\n \"createdBySubjectSlugs\": [\n \"user@example.com\",\n \"service-account\"\n ],\n \"applicationNames\": [\n \"tfy-llm-gateway\",\n \"order-service\"\n ],\n \"limit\": 200,\n \"sortDirection\": \"desc\",\n \"pageToken\": \"<string>\",\n \"tracingProjectFqn\": \"<string>\",\n \"dataRoutingDestination\": \"<string>\",\n \"filters\": [\n {\n \"value\": \"<string>\"\n }\n ],\n \"includeFeedbacks\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{controlPlaneURL}/api/svc/v1/spans/query")
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 \"startTime\": \"<string>\",\n \"endTime\": \"<string>\",\n \"traceIds\": [\n \"traceid1\",\n \"traceid2\"\n ],\n \"spanIds\": [\n \"spanId1\",\n \"spanId2\"\n ],\n \"parentSpanIds\": [\n \"\",\n \"parentSpanId1\",\n \"parentSpanId2\"\n ],\n \"createdBySubjectTypes\": [\n \"user\",\n \"virtualaccount\"\n ],\n \"createdBySubjectSlugs\": [\n \"user@example.com\",\n \"service-account\"\n ],\n \"applicationNames\": [\n \"tfy-llm-gateway\",\n \"order-service\"\n ],\n \"limit\": 200,\n \"sortDirection\": \"desc\",\n \"pageToken\": \"<string>\",\n \"tracingProjectFqn\": \"<string>\",\n \"dataRoutingDestination\": \"<string>\",\n \"filters\": [\n {\n \"value\": \"<string>\"\n }\n ],\n \"includeFeedbacks\": false\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"spanId": "<string>",
"traceId": "<string>",
"parentSpanId": "<string>",
"serviceName": "<string>",
"spanName": "<string>",
"spanKind": "<string>",
"scopeName": "<string>",
"scopeVersion": "<string>",
"timestamp": "<string>",
"durationNs": 123,
"statusCode": "<string>",
"statusMessage": "<string>",
"spanAttributes": {},
"events": [
{}
],
"createdBySubject": {
"subjectId": "<string>",
"subjectSlug": "<string>",
"subjectDisplayName": "<string>",
"subjectPatName": "<string>",
"subjectControllerName": "<string>",
"subjectExternalIdentitySlug": "<string>"
},
"feedbacks": [
"<array>"
]
}
],
"pagination": {
"limit": 10,
"nextPageToken": "<string>",
"previousPageToken": "<string>"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Start time in ISO 8601 format (e.g., 2025-03-12T00:00:09.872Z)
End time in ISO 8601 format (e.g., 2025-03-12T00:10:00.000Z). Defaults to current time if not provided.
Array of trace IDs to filter by
Example:
["traceid1", "traceid2"]
Array of span IDs to filter by
Example:
["spanId1", "spanId2"]
Array of parent span IDs to filter by
Example:
["", "parentSpanId1", "parentSpanId2"]
Array of subject types to filter by
Type of the authenticated subject. "user" for human users, "serviceaccount" (also known as virtual account) for programmatic access.
Available options:
user, team, serviceaccount, virtualaccount, external-identity, agent-identity, role Example:
["user", "virtualaccount"]
Array of subject slugs to filter by
Example:
["user@example.com", "service-account"]
Array of application names to filter by
Example:
["tfy-llm-gateway", "order-service"]
The maximum number of spans to return per page. Defaults to 200 if not provided.
Example:
200
Sort direction for results based on time. Defaults to descending (latest first)
Available options:
asc, desc Example:
"desc"
An opaque string that should be passed as-is from previous response for fetching the next page. Pass $response.pagination.nextPageToken from previous response for fetching the next page.
Tracing project FQN (e.g., truefoundry:tracing-project:tfy-default)
Data Routing Destination. One of tracingProjectFqn or dataRoutingDestination is required.
filters
(SpanFieldFilter · object | SpanAttributeFilter · object | GatewayRequestMetadataFilter · object)[] | null
Array of filters
- SpanFieldFilter
- SpanAttributeFilter
- GatewayRequestMetadataFilter
Show child attributes
Show child attributes
When true, feedback data is included in the response. When false, feedback data is excluded (returns empty array).
Was this page helpful?
⌘I