Get time-bucketed span metrics

curl --request POST \
  --url https://api.egp.scale.com/v5/spans/metrics \
  --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,
  "bucket_minutes": 30,
  "metrics": []
}
'

import requests

url = "https://api.egp.scale.com/v5/spans/metrics"

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,
    "bucket_minutes": 30,
    "metrics": []
}
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,
    bucket_minutes: 30,
    metrics: []
  })
};

fetch('https://api.egp.scale.com/v5/spans/metrics', 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",
  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,
    'bucket_minutes' => 30,
    'metrics' => [
        
    ]
  ]),
  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"

	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  \"bucket_minutes\": 30,\n  \"metrics\": []\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")
  .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  \"bucket_minutes\": 30,\n  \"metrics\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.egp.scale.com/v5/spans/metrics")

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  \"bucket_minutes\": 30,\n  \"metrics\": []\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "bucket_start": "2023-11-07T05:31:56Z",
      "count": 123,
      "error_count": 123,
      "p50_ms": 123,
      "p75_ms": 123,
      "p95_ms": 123
    }
  ],
  "bucket_minutes": 30
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Spans

Get time-bucketed span metrics

Compute time-bucketed span metrics over the requested window and filters.

metrics optionally selects count, errors, or latency (p50/p75/p95); omitting it preserves the all-metrics response. bucket_minutes sets the requested bucket size, but the effective size is enlarged automatically so the response never exceeds 100 buckets (the value actually used is returned in bucket_minutes). Both from_ts and to_ts are required. A reversed time window (from_ts after to_ts) is rejected with 422. The underlying scan is capped at 50,000 matching spans, so metrics over a very large window may be based on a truncated set. Results are narrowed to traces the caller is authorized to read.

POST

spans

metrics

Get time-bucketed span metrics

curl --request POST \
  --url https://api.egp.scale.com/v5/spans/metrics \
  --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,
  "bucket_minutes": 30,
  "metrics": []
}
'

import requests

url = "https://api.egp.scale.com/v5/spans/metrics"

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,
    "bucket_minutes": 30,
    "metrics": []
}
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,
    bucket_minutes: 30,
    metrics: []
  })
};

fetch('https://api.egp.scale.com/v5/spans/metrics', 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",
  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,
    'bucket_minutes' => 30,
    'metrics' => [
        
    ]
  ]),
  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"

	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  \"bucket_minutes\": 30,\n  \"metrics\": []\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")
  .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  \"bucket_minutes\": 30,\n  \"metrics\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.egp.scale.com/v5/spans/metrics")

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  \"bucket_minutes\": 30,\n  \"metrics\": []\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "bucket_start": "2023-11-07T05:31:56Z",
      "count": 123,
      "error_count": 123,
      "p50_ms": 123,
      "p75_ms": 123,
      "p95_ms": 123
    }
  ],
  "bucket_minutes": 30
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

x-api-key

string

header

required

Headers

x-selected-account-id

string | null

Query Parameters

from_ts

string<date-time> | null

The starting (oldest) timestamp in ISO format.

to_ts

string<date-time> | null

The ending (most recent) timestamp in ISO format.

Body

application/json

parents_only

boolean

Only fetch spans that are the top-level (ie. have no parent_id)

span_ids

string[]

Filter by span IDs

trace_ids

string[]

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.

excluded_span_ids

string[]

List of span IDs to exclude from results

excluded_trace_ids

string[]

List of trace IDs to exclude from results

group_id

string

Filter by group ID

parent_ids

string[]

Filter to the direct children of any of these parent span IDs

names

string[]

Filter by trace/span name

statuses

enum<string>[]

Filter on span status

Available options:

SUCCESS,

ERROR,

CANCELED

types

enum<string>[]

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

search_texts

string[]

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.

extra_metadata

Extra Metadata · object

Filter on custom metadata key-value pairs

application_variant_ids

string[]

Filter by application variant IDs

assessment_types

string[]

Filter to spans that have at least one assessment of these types

acp_types

string[]

Filter by ACP types

agentex_agent_names

string[]

Filter by Agentex agent names

agentex_agent_ids

string[]

Filter by Agentex agent IDs

min_duration_ms

integer

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.

max_duration_ms

integer

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.

bucket_minutes

integer

default:30

Size of each time bucket in minutes

metrics

enum<string>[]

Metric groups to compute. Omit or pass an empty list to compute all groups.

An independently loadable metric group for the traces chart.

Available options:

count,

errors,

latency

Response

Successful Response

items

SpansMetricsBucket · object[]

required

Show child attributes

bucket_minutes

integer

default:30

Effective bucket size in minutes

Inference

Questions

Rubrics

Vector Stores

Files

Models

Agent Configs

Datasets

Dataset Items

Evaluations

Evaluation Groups

Evaluation Charts

Evaluation Dashboards

Evaluation Items

Spans

Span Assessment

Annotation Tasks

Credentials

Agentex Cloud Build

Agentex Cloud Deploy

Agentex Agent

SGP Cloud Secrets

Get time-bucketed span metrics

Authorizations

Headers

Query Parameters

Body

Response