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,
"showVerbose": true
}
'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,
"showVerbose": True
}
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,
showVerbose: true
})
};
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,
'showVerbose' => true
]),
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 \"showVerbose\": true\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 \"showVerbose\": true\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 \"showVerbose\": true\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"spanId": "<string>",
"traceId": "<string>",
"parentSpanId": "<string>",
"tfyParentSpanId": "<string>",
"serviceName": "<string>",
"spanName": "<string>",
"spanKind": "<string>",
"scopeName": "<string>",
"scopeVersion": "<string>",
"timestamp": "<string>",
"durationNs": 123,
"statusCode": "<string>",
"statusMessage": "<string>",
"spanAttributes": {},
"events": [
{}
],
"createdBySubject": {
"subjectId": "<string>",
"subjectType": "user",
"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,
"showVerbose": true
}
'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,
"showVerbose": True
}
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,
showVerbose: true
})
};
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,
'showVerbose' => true
]),
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 \"showVerbose\": true\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 \"showVerbose\": true\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 \"showVerbose\": true\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"spanId": "<string>",
"traceId": "<string>",
"parentSpanId": "<string>",
"tfyParentSpanId": "<string>",
"serviceName": "<string>",
"spanName": "<string>",
"spanKind": "<string>",
"scopeName": "<string>",
"scopeVersion": "<string>",
"timestamp": "<string>",
"durationNs": 123,
"statusCode": "<string>",
"statusMessage": "<string>",
"spanAttributes": {},
"events": [
{}
],
"createdBySubject": {
"subjectId": "<string>",
"subjectType": "user",
"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.
Query Parameters
When false, gateway input and output are omitted from the response so those columns are not read. Defaults to true.
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, agent-identity, agent, agent-channel-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. Values above the server-configured maximum (default 200) are capped to it, and the applied value comes back in pagination.limit.
Required range:
1 <= x <= 20000Example:
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).
When false, spans whose TfyLogLevel is debug are hidden. Omit or set true to include them.
Was this page helpful?