Skip to main content
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

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
startTime
string
required

Start time in ISO 8601 format (e.g., 2025-03-12T00:00:09.872Z)

​
endTime
string | null

End time in ISO 8601 format (e.g., 2025-03-12T00:10:00.000Z). Defaults to current time if not provided.

​
traceIds
string[] | null

Array of trace IDs to filter by

Example:
["traceid1", "traceid2"]
​
spanIds
string[] | null

Array of span IDs to filter by

Example:
["spanId1", "spanId2"]
​
parentSpanIds
string[] | null

Array of parent span IDs to filter by

Example:
["", "parentSpanId1", "parentSpanId2"]
​
createdBySubjectTypes
enum<string>[] | null

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"]
​
createdBySubjectSlugs
string[] | null

Array of subject slugs to filter by

Example:
["user@example.com", "service-account"]
​
applicationNames
string[] | null

Array of application names to filter by

Example:
["tfy-llm-gateway", "order-service"]
​
limit
integer | null

The maximum number of spans to return per page. Defaults to 200 if not provided.

Example:

200

​
sortDirection
enum<string> | null

Sort direction for results based on time. Defaults to descending (latest first)

Available options:
asc,
desc
Example:

"desc"

​
pageToken
string | null

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.

​
tracingProjectFqn
string | null

Tracing project FQN (e.g., truefoundry:tracing-project:tfy-default)

​
dataRoutingDestination
string | null

Data Routing Destination. One of tracingProjectFqn or dataRoutingDestination is required.

​
filters
(SpanFieldFilter · object | SpanAttributeFilter · object | GatewayRequestMetadataFilter · object)[] | null

Array of filters

​
includeFeedbacks
boolean | null
default:false

When true, feedback data is included in the response. When false, feedback data is excluded (returns empty array).

Response

200 - application/json

Returns all the spans matching the query.

​
data
TraceSpan · object[]
required

Array of flat spans

​
pagination
TokenPagination · object
required

Pagination information