Search spans
curl --request POST \
--url https://api.egp.scale.com/v5/spans/search \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"parents_only": true,
"span_ids": [
"<string>"
],
"trace_ids": [
"<string>"
],
"excluded_span_ids": [
"<string>"
],
"excluded_trace_ids": [
"<string>"
],
"group_id": "<string>",
"parent_ids": [
"<string>"
],
"names": [
"<string>"
],
"statuses": [],
"types": [],
"search_texts": [
"<string>"
],
"extra_metadata": {},
"application_variant_ids": [
"<string>"
],
"assessment_types": [
"<string>"
],
"acp_types": [
"<string>"
],
"agentex_agent_names": [
"<string>"
],
"agentex_agent_ids": [
"<string>"
],
"min_duration_ms": 123,
"max_duration_ms": 123
}
'import requests
url = "https://api.egp.scale.com/v5/spans/search"
payload = {
"parents_only": True,
"span_ids": ["<string>"],
"trace_ids": ["<string>"],
"excluded_span_ids": ["<string>"],
"excluded_trace_ids": ["<string>"],
"group_id": "<string>",
"parent_ids": ["<string>"],
"names": ["<string>"],
"statuses": [],
"types": [],
"search_texts": ["<string>"],
"extra_metadata": {},
"application_variant_ids": ["<string>"],
"assessment_types": ["<string>"],
"acp_types": ["<string>"],
"agentex_agent_names": ["<string>"],
"agentex_agent_ids": ["<string>"],
"min_duration_ms": 123,
"max_duration_ms": 123
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
parents_only: true,
span_ids: ['<string>'],
trace_ids: ['<string>'],
excluded_span_ids: ['<string>'],
excluded_trace_ids: ['<string>'],
group_id: '<string>',
parent_ids: ['<string>'],
names: ['<string>'],
statuses: [],
types: [],
search_texts: ['<string>'],
extra_metadata: {},
application_variant_ids: ['<string>'],
assessment_types: ['<string>'],
acp_types: ['<string>'],
agentex_agent_names: ['<string>'],
agentex_agent_ids: ['<string>'],
min_duration_ms: 123,
max_duration_ms: 123
})
};
fetch('https://api.egp.scale.com/v5/spans/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.egp.scale.com/v5/spans/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([
'parents_only' => true,
'span_ids' => [
'<string>'
],
'trace_ids' => [
'<string>'
],
'excluded_span_ids' => [
'<string>'
],
'excluded_trace_ids' => [
'<string>'
],
'group_id' => '<string>',
'parent_ids' => [
'<string>'
],
'names' => [
'<string>'
],
'statuses' => [
],
'types' => [
],
'search_texts' => [
'<string>'
],
'extra_metadata' => [
],
'application_variant_ids' => [
'<string>'
],
'assessment_types' => [
'<string>'
],
'acp_types' => [
'<string>'
],
'agentex_agent_names' => [
'<string>'
],
'agentex_agent_ids' => [
'<string>'
],
'min_duration_ms' => 123,
'max_duration_ms' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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.egp.scale.com/v5/spans/search"
payload := strings.NewReader("{\n \"parents_only\": true,\n \"span_ids\": [\n \"<string>\"\n ],\n \"trace_ids\": [\n \"<string>\"\n ],\n \"excluded_span_ids\": [\n \"<string>\"\n ],\n \"excluded_trace_ids\": [\n \"<string>\"\n ],\n \"group_id\": \"<string>\",\n \"parent_ids\": [\n \"<string>\"\n ],\n \"names\": [\n \"<string>\"\n ],\n \"statuses\": [],\n \"types\": [],\n \"search_texts\": [\n \"<string>\"\n ],\n \"extra_metadata\": {},\n \"application_variant_ids\": [\n \"<string>\"\n ],\n \"assessment_types\": [\n \"<string>\"\n ],\n \"acp_types\": [\n \"<string>\"\n ],\n \"agentex_agent_names\": [\n \"<string>\"\n ],\n \"agentex_agent_ids\": [\n \"<string>\"\n ],\n \"min_duration_ms\": 123,\n \"max_duration_ms\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.egp.scale.com/v5/spans/search")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"parents_only\": true,\n \"span_ids\": [\n \"<string>\"\n ],\n \"trace_ids\": [\n \"<string>\"\n ],\n \"excluded_span_ids\": [\n \"<string>\"\n ],\n \"excluded_trace_ids\": [\n \"<string>\"\n ],\n \"group_id\": \"<string>\",\n \"parent_ids\": [\n \"<string>\"\n ],\n \"names\": [\n \"<string>\"\n ],\n \"statuses\": [],\n \"types\": [],\n \"search_texts\": [\n \"<string>\"\n ],\n \"extra_metadata\": {},\n \"application_variant_ids\": [\n \"<string>\"\n ],\n \"assessment_types\": [\n \"<string>\"\n ],\n \"acp_types\": [\n \"<string>\"\n ],\n \"agentex_agent_names\": [\n \"<string>\"\n ],\n \"agentex_agent_ids\": [\n \"<string>\"\n ],\n \"min_duration_ms\": 123,\n \"max_duration_ms\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v5/spans/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"parents_only\": true,\n \"span_ids\": [\n \"<string>\"\n ],\n \"trace_ids\": [\n \"<string>\"\n ],\n \"excluded_span_ids\": [\n \"<string>\"\n ],\n \"excluded_trace_ids\": [\n \"<string>\"\n ],\n \"group_id\": \"<string>\",\n \"parent_ids\": [\n \"<string>\"\n ],\n \"names\": [\n \"<string>\"\n ],\n \"statuses\": [],\n \"types\": [],\n \"search_texts\": [\n \"<string>\"\n ],\n \"extra_metadata\": {},\n \"application_variant_ids\": [\n \"<string>\"\n ],\n \"assessment_types\": [\n \"<string>\"\n ],\n \"acp_types\": [\n \"<string>\"\n ],\n \"agentex_agent_names\": [\n \"<string>\"\n ],\n \"agentex_agent_ids\": [\n \"<string>\"\n ],\n \"min_duration_ms\": 123,\n \"max_duration_ms\": 123\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"name": "<string>",
"trace_id": "<string>",
"start_timestamp": "2023-11-07T05:31:56Z",
"account_id": "<string>",
"object": "span",
"created_by": {
"id": "<string>",
"type": "user",
"object": "identity"
},
"parent_id": "<string>",
"group_id": "<string>",
"end_timestamp": "2023-11-07T05:31:56Z",
"input": {},
"output": {},
"metadata": {},
"expected": {},
"status": "SUCCESS",
"type": "STANDALONE",
"application_interaction_id": "<string>",
"application_variant_id": "<string>"
}
],
"total": 123,
"has_more": true,
"object": "list",
"limit": 100,
"next_cursor": "<string>",
"prev_cursor": "<string>",
"window_truncated": true,
"effective_from_ts": "2023-11-07T05:31:56Z",
"effective_to_ts": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Spans
Search spans
Search and list spans matching a set of filters, returning a keyset-paginated page.
Filters in the request body include trace and span ids, names, statuses,
types, free-text search, metadata, duration bounds, and more, scoped to an
optional time window. Results are keyset-paginated on indexed columns rather
than offset-paginated, and total is not computed (it is always 0); use the
pagination cursors to page through results. Reads route to Postgres or the
ClickHouse-backed tracing service per account (with Postgres fallback outside
strict mode), and results are narrowed to traces the caller is authorized to
read — a filter that resolves to no authorized traces yields an empty page
rather than an error. A reversed time window (from_ts after to_ts) is
rejected with 422, as is a request whose combined trace_ids, span_ids,
excluded_span_ids, excluded_trace_ids, and parent_ids count exceeds
10000.
POST
/
v5
/
spans
/
search
Search spans
curl --request POST \
--url https://api.egp.scale.com/v5/spans/search \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"parents_only": true,
"span_ids": [
"<string>"
],
"trace_ids": [
"<string>"
],
"excluded_span_ids": [
"<string>"
],
"excluded_trace_ids": [
"<string>"
],
"group_id": "<string>",
"parent_ids": [
"<string>"
],
"names": [
"<string>"
],
"statuses": [],
"types": [],
"search_texts": [
"<string>"
],
"extra_metadata": {},
"application_variant_ids": [
"<string>"
],
"assessment_types": [
"<string>"
],
"acp_types": [
"<string>"
],
"agentex_agent_names": [
"<string>"
],
"agentex_agent_ids": [
"<string>"
],
"min_duration_ms": 123,
"max_duration_ms": 123
}
'import requests
url = "https://api.egp.scale.com/v5/spans/search"
payload = {
"parents_only": True,
"span_ids": ["<string>"],
"trace_ids": ["<string>"],
"excluded_span_ids": ["<string>"],
"excluded_trace_ids": ["<string>"],
"group_id": "<string>",
"parent_ids": ["<string>"],
"names": ["<string>"],
"statuses": [],
"types": [],
"search_texts": ["<string>"],
"extra_metadata": {},
"application_variant_ids": ["<string>"],
"assessment_types": ["<string>"],
"acp_types": ["<string>"],
"agentex_agent_names": ["<string>"],
"agentex_agent_ids": ["<string>"],
"min_duration_ms": 123,
"max_duration_ms": 123
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
parents_only: true,
span_ids: ['<string>'],
trace_ids: ['<string>'],
excluded_span_ids: ['<string>'],
excluded_trace_ids: ['<string>'],
group_id: '<string>',
parent_ids: ['<string>'],
names: ['<string>'],
statuses: [],
types: [],
search_texts: ['<string>'],
extra_metadata: {},
application_variant_ids: ['<string>'],
assessment_types: ['<string>'],
acp_types: ['<string>'],
agentex_agent_names: ['<string>'],
agentex_agent_ids: ['<string>'],
min_duration_ms: 123,
max_duration_ms: 123
})
};
fetch('https://api.egp.scale.com/v5/spans/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.egp.scale.com/v5/spans/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([
'parents_only' => true,
'span_ids' => [
'<string>'
],
'trace_ids' => [
'<string>'
],
'excluded_span_ids' => [
'<string>'
],
'excluded_trace_ids' => [
'<string>'
],
'group_id' => '<string>',
'parent_ids' => [
'<string>'
],
'names' => [
'<string>'
],
'statuses' => [
],
'types' => [
],
'search_texts' => [
'<string>'
],
'extra_metadata' => [
],
'application_variant_ids' => [
'<string>'
],
'assessment_types' => [
'<string>'
],
'acp_types' => [
'<string>'
],
'agentex_agent_names' => [
'<string>'
],
'agentex_agent_ids' => [
'<string>'
],
'min_duration_ms' => 123,
'max_duration_ms' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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.egp.scale.com/v5/spans/search"
payload := strings.NewReader("{\n \"parents_only\": true,\n \"span_ids\": [\n \"<string>\"\n ],\n \"trace_ids\": [\n \"<string>\"\n ],\n \"excluded_span_ids\": [\n \"<string>\"\n ],\n \"excluded_trace_ids\": [\n \"<string>\"\n ],\n \"group_id\": \"<string>\",\n \"parent_ids\": [\n \"<string>\"\n ],\n \"names\": [\n \"<string>\"\n ],\n \"statuses\": [],\n \"types\": [],\n \"search_texts\": [\n \"<string>\"\n ],\n \"extra_metadata\": {},\n \"application_variant_ids\": [\n \"<string>\"\n ],\n \"assessment_types\": [\n \"<string>\"\n ],\n \"acp_types\": [\n \"<string>\"\n ],\n \"agentex_agent_names\": [\n \"<string>\"\n ],\n \"agentex_agent_ids\": [\n \"<string>\"\n ],\n \"min_duration_ms\": 123,\n \"max_duration_ms\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.egp.scale.com/v5/spans/search")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"parents_only\": true,\n \"span_ids\": [\n \"<string>\"\n ],\n \"trace_ids\": [\n \"<string>\"\n ],\n \"excluded_span_ids\": [\n \"<string>\"\n ],\n \"excluded_trace_ids\": [\n \"<string>\"\n ],\n \"group_id\": \"<string>\",\n \"parent_ids\": [\n \"<string>\"\n ],\n \"names\": [\n \"<string>\"\n ],\n \"statuses\": [],\n \"types\": [],\n \"search_texts\": [\n \"<string>\"\n ],\n \"extra_metadata\": {},\n \"application_variant_ids\": [\n \"<string>\"\n ],\n \"assessment_types\": [\n \"<string>\"\n ],\n \"acp_types\": [\n \"<string>\"\n ],\n \"agentex_agent_names\": [\n \"<string>\"\n ],\n \"agentex_agent_ids\": [\n \"<string>\"\n ],\n \"min_duration_ms\": 123,\n \"max_duration_ms\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v5/spans/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"parents_only\": true,\n \"span_ids\": [\n \"<string>\"\n ],\n \"trace_ids\": [\n \"<string>\"\n ],\n \"excluded_span_ids\": [\n \"<string>\"\n ],\n \"excluded_trace_ids\": [\n \"<string>\"\n ],\n \"group_id\": \"<string>\",\n \"parent_ids\": [\n \"<string>\"\n ],\n \"names\": [\n \"<string>\"\n ],\n \"statuses\": [],\n \"types\": [],\n \"search_texts\": [\n \"<string>\"\n ],\n \"extra_metadata\": {},\n \"application_variant_ids\": [\n \"<string>\"\n ],\n \"assessment_types\": [\n \"<string>\"\n ],\n \"acp_types\": [\n \"<string>\"\n ],\n \"agentex_agent_names\": [\n \"<string>\"\n ],\n \"agentex_agent_ids\": [\n \"<string>\"\n ],\n \"min_duration_ms\": 123,\n \"max_duration_ms\": 123\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"name": "<string>",
"trace_id": "<string>",
"start_timestamp": "2023-11-07T05:31:56Z",
"account_id": "<string>",
"object": "span",
"created_by": {
"id": "<string>",
"type": "user",
"object": "identity"
},
"parent_id": "<string>",
"group_id": "<string>",
"end_timestamp": "2023-11-07T05:31:56Z",
"input": {},
"output": {},
"metadata": {},
"expected": {},
"status": "SUCCESS",
"type": "STANDALONE",
"application_interaction_id": "<string>",
"application_variant_id": "<string>"
}
],
"total": 123,
"has_more": true,
"object": "list",
"limit": 100,
"next_cursor": "<string>",
"prev_cursor": "<string>",
"window_truncated": true,
"effective_from_ts": "2023-11-07T05:31:56Z",
"effective_to_ts": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Headers
Query Parameters
Required range:
1 <= x <= 10000Available options:
asc, desc The starting (oldest) timestamp in ISO format.
The ending (most recent) timestamp in ISO format.
Body
application/json
Only fetch spans that are the top-level (ie. have no parent_id)
Filter by span IDs
Filter by trace IDs. The combined count of trace_ids, span_ids, excluded_span_ids, excluded_trace_ids, and parent_ids may not exceed 10000. A request over that returns 422.
List of span IDs to exclude from results
List of trace IDs to exclude from results
Filter by group ID
Filter to the direct children of any of these parent span IDs
Filter by trace/span name
Filter on span status
Available options:
SUCCESS, ERROR, CANCELED Available options:
TEXT_INPUT, TEXT_OUTPUT, COMPLETION_INPUT, COMPLETION, KB_RETRIEVAL, KB_INPUT, RERANKING, EXTERNAL_ENDPOINT, PROMPT_ENGINEERING, DOCUMENT_INPUT, MAP_REDUCE, DOCUMENT_SEARCH, DOCUMENT_PROMPT, CUSTOM, CODE_EXECUTION, DATA_MANIPULATION, EVALUATION, FILE_RETRIEVAL, KB_ADD_CHUNK, KB_MANAGEMENT, GUARDRAIL, OUTPUT_GUARDRAIL, TRACER, AGENT_TRACER, AGENT_WORKFLOW, STANDALONE Case-insensitive substring search across span name, input, output, and metadata (no tokenization or stemming). Multiple terms are ANDed, and UUID-shaped terms match trace IDs instead. Substring means mid-word fragments match, while an inflected form such as a plural matches only where it appears literally. A span must match every non-UUID term, and each term may match any of the searched fields. UUID matches are ORed onto the text match. Each term must be at least 2 characters. For exact trace ID lookup, use the trace_ids filter. Accounts still served by the legacy trace store match differently until migrated: terms match as stemmed whole words rather than substrings, only input and output are searched, the 2-character minimum is not enforced, and characters like :, |, or ! inside a term may be interpreted as query operators or cause an error.
Filter on custom metadata key-value pairs
Filter by application variant IDs
Filter to spans that have at least one assessment of these types
Filter by ACP types
Filter by Agentex agent names
Filter by Agentex agent IDs
Minimum span duration in milliseconds (inclusive). An in-flight span with no end time has no known duration and is treated as unbounded, so it matches every minimum.
Maximum span duration in milliseconds (inclusive). An in-flight span with no end time has no known duration and is treated as unbounded, so it never falls within a maximum and is excluded.
Response
Successful Response
Span search page carrying sgp-traces' opaque pagination cursors.
The Postgres path keyset-paginates on the span id and leaves these unset. The ClickHouse path returns opaque cursors that clients must round-trip.
Show child attributes
Show child attributes
The total of items that match the query. This is greater than or equal to the number of items returned.
Whether there are more items left to be fetched.
Allowed value:
"list"The maximum number of items to return.
Pass as starting_after to fetch the next page. None when there is no next page.
Pass as ending_before to fetch the previous page. None when on the first page.
True when the requested window exceeded the 90 day maximum and was clamped, so results cover only effective_from_ts..effective_to_ts. null when no clamp occurred.
Resolved start of the searched window. null when no clamp occurred.
Resolved end of the searched window. null when no clamp occurred.