Get span metrics grouped by name
curl --request POST \
--url https://api.egp.scale.com/v5/spans/metrics/by-span \
--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,
"limit": 100,
"offset": 0,
"sort_by": "total_ms"
}
'import requests
url = "https://api.egp.scale.com/v5/spans/metrics/by-span"
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,
"limit": 100,
"offset": 0,
"sort_by": "total_ms"
}
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,
limit: 100,
offset: 0,
sort_by: 'total_ms'
})
};
fetch('https://api.egp.scale.com/v5/spans/metrics/by-span', 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/metrics/by-span",
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,
'limit' => 100,
'offset' => 0,
'sort_by' => 'total_ms'
]),
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/metrics/by-span"
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 \"limit\": 100,\n \"offset\": 0,\n \"sort_by\": \"total_ms\"\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/metrics/by-span")
.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 \"limit\": 100,\n \"offset\": 0,\n \"sort_by\": \"total_ms\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v5/spans/metrics/by-span")
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 \"limit\": 100,\n \"offset\": 0,\n \"sort_by\": \"total_ms\"\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"span_name": "<string>",
"count": 123,
"min_ms": 123,
"avg_ms": 123,
"p50_ms": 123,
"p90_ms": 123,
"p95_ms": 123,
"p99_ms": 123,
"max_ms": 123,
"total_ms": 123,
"total_time_pct": 123,
"avg_per_trace": 123
}
],
"totals": {
"total_traces": 123,
"total_spans": 123
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Spans
Get span metrics grouped by name
Compute duration metrics aggregated by span name across the filtered set.
Returns one row per distinct span name plus overall totals (unique traces and
total spans considered). Each row includes occurrence count, min/avg/max and
p50/p90/p95/p99 durations, summed duration, share of total time, and average
occurrences per trace — use this to profile which span names dominate latency.
Results can be sorted (sort_by, default total_ms) and paginated with
limit/offset, and are narrowed to traces the caller is authorized to read.
A reversed time window (from_ts after to_ts) is rejected with 422.
POST
/
v5
/
spans
/
metrics
/
by-span
Get span metrics grouped by name
curl --request POST \
--url https://api.egp.scale.com/v5/spans/metrics/by-span \
--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,
"limit": 100,
"offset": 0,
"sort_by": "total_ms"
}
'import requests
url = "https://api.egp.scale.com/v5/spans/metrics/by-span"
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,
"limit": 100,
"offset": 0,
"sort_by": "total_ms"
}
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,
limit: 100,
offset: 0,
sort_by: 'total_ms'
})
};
fetch('https://api.egp.scale.com/v5/spans/metrics/by-span', 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/metrics/by-span",
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,
'limit' => 100,
'offset' => 0,
'sort_by' => 'total_ms'
]),
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/metrics/by-span"
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 \"limit\": 100,\n \"offset\": 0,\n \"sort_by\": \"total_ms\"\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/metrics/by-span")
.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 \"limit\": 100,\n \"offset\": 0,\n \"sort_by\": \"total_ms\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v5/spans/metrics/by-span")
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 \"limit\": 100,\n \"offset\": 0,\n \"sort_by\": \"total_ms\"\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"span_name": "<string>",
"count": 123,
"min_ms": 123,
"avg_ms": 123,
"p50_ms": 123,
"p90_ms": 123,
"p95_ms": 123,
"p99_ms": 123,
"max_ms": 123,
"total_ms": 123,
"total_time_pct": 123,
"avg_per_trace": 123
}
],
"totals": {
"total_traces": 123,
"total_spans": 123
}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Headers
Query Parameters
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.
Max number of span groups to return
Offset for pagination of span groups
Field to sort by: 'total_ms', 'max_ms', 'avg_ms', or 'count'