curl --request POST \
--url https://api.egp.scale.com/v5/spans \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"trace_id": "<string>",
"start_timestamp": "2023-11-07T05:31:56Z",
"id": "<string>",
"parent_id": "<string>",
"group_id": "<string>",
"end_timestamp": "2023-11-07T05:31:56Z",
"input": {},
"output": {},
"metadata": {},
"status": "SUCCESS",
"type": "STANDALONE",
"application_interaction_id": "<string>",
"application_variant_id": "<string>",
"expected": {},
"obs_trace_id": "<string>",
"obs_span_id": "<string>"
}
'import requests
url = "https://api.egp.scale.com/v5/spans"
payload = {
"name": "<string>",
"trace_id": "<string>",
"start_timestamp": "2023-11-07T05:31:56Z",
"id": "<string>",
"parent_id": "<string>",
"group_id": "<string>",
"end_timestamp": "2023-11-07T05:31:56Z",
"input": {},
"output": {},
"metadata": {},
"status": "SUCCESS",
"type": "STANDALONE",
"application_interaction_id": "<string>",
"application_variant_id": "<string>",
"expected": {},
"obs_trace_id": "<string>",
"obs_span_id": "<string>"
}
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({
name: '<string>',
trace_id: '<string>',
start_timestamp: '2023-11-07T05:31:56Z',
id: '<string>',
parent_id: '<string>',
group_id: '<string>',
end_timestamp: '2023-11-07T05:31:56Z',
input: {},
output: {},
metadata: {},
status: 'SUCCESS',
type: 'STANDALONE',
application_interaction_id: '<string>',
application_variant_id: '<string>',
expected: {},
obs_trace_id: '<string>',
obs_span_id: '<string>'
})
};
fetch('https://api.egp.scale.com/v5/spans', 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",
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([
'name' => '<string>',
'trace_id' => '<string>',
'start_timestamp' => '2023-11-07T05:31:56Z',
'id' => '<string>',
'parent_id' => '<string>',
'group_id' => '<string>',
'end_timestamp' => '2023-11-07T05:31:56Z',
'input' => [
],
'output' => [
],
'metadata' => [
],
'status' => 'SUCCESS',
'type' => 'STANDALONE',
'application_interaction_id' => '<string>',
'application_variant_id' => '<string>',
'expected' => [
],
'obs_trace_id' => '<string>',
'obs_span_id' => '<string>'
]),
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"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"trace_id\": \"<string>\",\n \"start_timestamp\": \"2023-11-07T05:31:56Z\",\n \"id\": \"<string>\",\n \"parent_id\": \"<string>\",\n \"group_id\": \"<string>\",\n \"end_timestamp\": \"2023-11-07T05:31:56Z\",\n \"input\": {},\n \"output\": {},\n \"metadata\": {},\n \"status\": \"SUCCESS\",\n \"type\": \"STANDALONE\",\n \"application_interaction_id\": \"<string>\",\n \"application_variant_id\": \"<string>\",\n \"expected\": {},\n \"obs_trace_id\": \"<string>\",\n \"obs_span_id\": \"<string>\"\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")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"trace_id\": \"<string>\",\n \"start_timestamp\": \"2023-11-07T05:31:56Z\",\n \"id\": \"<string>\",\n \"parent_id\": \"<string>\",\n \"group_id\": \"<string>\",\n \"end_timestamp\": \"2023-11-07T05:31:56Z\",\n \"input\": {},\n \"output\": {},\n \"metadata\": {},\n \"status\": \"SUCCESS\",\n \"type\": \"STANDALONE\",\n \"application_interaction_id\": \"<string>\",\n \"application_variant_id\": \"<string>\",\n \"expected\": {},\n \"obs_trace_id\": \"<string>\",\n \"obs_span_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v5/spans")
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 \"name\": \"<string>\",\n \"trace_id\": \"<string>\",\n \"start_timestamp\": \"2023-11-07T05:31:56Z\",\n \"id\": \"<string>\",\n \"parent_id\": \"<string>\",\n \"group_id\": \"<string>\",\n \"end_timestamp\": \"2023-11-07T05:31:56Z\",\n \"input\": {},\n \"output\": {},\n \"metadata\": {},\n \"status\": \"SUCCESS\",\n \"type\": \"STANDALONE\",\n \"application_interaction_id\": \"<string>\",\n \"application_variant_id\": \"<string>\",\n \"expected\": {},\n \"obs_trace_id\": \"<string>\",\n \"obs_span_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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>",
"obs_trace_id": "<string>",
"obs_span_id": "<string>",
"input_tokens": 2147483647,
"output_tokens": 2147483647
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "<string>"
}Create a span
Create a single span and return the persisted span.
Use this for one-off span ingestion; to write many spans in one request use
POST /v5/spans/batch. When id is omitted the server generates a UUID.
Depending on per-account server configuration the span is persisted to the
legacy trace store, to the tracing service, or both. end_timestamp
must not precede start_timestamp, which is rejected with a 422. When the
tracing service is the primary store, its 400, 413 and 422 rejections keep that
status and detail, as does a 403 when the request carried its own API key, and
every other failure returns a 503 with a Retry-After header. A span whose parent
belongs to another trace is rejected with 409 before either store is written. The
parent is looked up in Postgres, so that check ends once the account’s spans stop
being written there. Which writes the tracing service rejects depends in part on
its storage engine: on Postgres deployments a NUL byte or invalid UTF-8 inside
trace_id, id, parent_id or group_id rejects the span with a 400
naming the field, because replacing the byte would change the identity the
response echoes; a NUL byte or invalid UTF-8 in any other field is replaced with
U+FFFD and the span is persisted. ClickHouse deployments store the bytes verbatim.
Credential redaction: values in the free-form input, output, metadata,
and expected objects, and in name, that are credential-shaped (bearer/JWT,
API keys, connection-string passwords) or under a credential-named key are replaced
with [REDACTED:credential] before the span is persisted, so the stored and
returned span reflects the redacted value.
curl --request POST \
--url https://api.egp.scale.com/v5/spans \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "<string>",
"trace_id": "<string>",
"start_timestamp": "2023-11-07T05:31:56Z",
"id": "<string>",
"parent_id": "<string>",
"group_id": "<string>",
"end_timestamp": "2023-11-07T05:31:56Z",
"input": {},
"output": {},
"metadata": {},
"status": "SUCCESS",
"type": "STANDALONE",
"application_interaction_id": "<string>",
"application_variant_id": "<string>",
"expected": {},
"obs_trace_id": "<string>",
"obs_span_id": "<string>"
}
'import requests
url = "https://api.egp.scale.com/v5/spans"
payload = {
"name": "<string>",
"trace_id": "<string>",
"start_timestamp": "2023-11-07T05:31:56Z",
"id": "<string>",
"parent_id": "<string>",
"group_id": "<string>",
"end_timestamp": "2023-11-07T05:31:56Z",
"input": {},
"output": {},
"metadata": {},
"status": "SUCCESS",
"type": "STANDALONE",
"application_interaction_id": "<string>",
"application_variant_id": "<string>",
"expected": {},
"obs_trace_id": "<string>",
"obs_span_id": "<string>"
}
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({
name: '<string>',
trace_id: '<string>',
start_timestamp: '2023-11-07T05:31:56Z',
id: '<string>',
parent_id: '<string>',
group_id: '<string>',
end_timestamp: '2023-11-07T05:31:56Z',
input: {},
output: {},
metadata: {},
status: 'SUCCESS',
type: 'STANDALONE',
application_interaction_id: '<string>',
application_variant_id: '<string>',
expected: {},
obs_trace_id: '<string>',
obs_span_id: '<string>'
})
};
fetch('https://api.egp.scale.com/v5/spans', 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",
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([
'name' => '<string>',
'trace_id' => '<string>',
'start_timestamp' => '2023-11-07T05:31:56Z',
'id' => '<string>',
'parent_id' => '<string>',
'group_id' => '<string>',
'end_timestamp' => '2023-11-07T05:31:56Z',
'input' => [
],
'output' => [
],
'metadata' => [
],
'status' => 'SUCCESS',
'type' => 'STANDALONE',
'application_interaction_id' => '<string>',
'application_variant_id' => '<string>',
'expected' => [
],
'obs_trace_id' => '<string>',
'obs_span_id' => '<string>'
]),
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"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"trace_id\": \"<string>\",\n \"start_timestamp\": \"2023-11-07T05:31:56Z\",\n \"id\": \"<string>\",\n \"parent_id\": \"<string>\",\n \"group_id\": \"<string>\",\n \"end_timestamp\": \"2023-11-07T05:31:56Z\",\n \"input\": {},\n \"output\": {},\n \"metadata\": {},\n \"status\": \"SUCCESS\",\n \"type\": \"STANDALONE\",\n \"application_interaction_id\": \"<string>\",\n \"application_variant_id\": \"<string>\",\n \"expected\": {},\n \"obs_trace_id\": \"<string>\",\n \"obs_span_id\": \"<string>\"\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")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"trace_id\": \"<string>\",\n \"start_timestamp\": \"2023-11-07T05:31:56Z\",\n \"id\": \"<string>\",\n \"parent_id\": \"<string>\",\n \"group_id\": \"<string>\",\n \"end_timestamp\": \"2023-11-07T05:31:56Z\",\n \"input\": {},\n \"output\": {},\n \"metadata\": {},\n \"status\": \"SUCCESS\",\n \"type\": \"STANDALONE\",\n \"application_interaction_id\": \"<string>\",\n \"application_variant_id\": \"<string>\",\n \"expected\": {},\n \"obs_trace_id\": \"<string>\",\n \"obs_span_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v5/spans")
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 \"name\": \"<string>\",\n \"trace_id\": \"<string>\",\n \"start_timestamp\": \"2023-11-07T05:31:56Z\",\n \"id\": \"<string>\",\n \"parent_id\": \"<string>\",\n \"group_id\": \"<string>\",\n \"end_timestamp\": \"2023-11-07T05:31:56Z\",\n \"input\": {},\n \"output\": {},\n \"metadata\": {},\n \"status\": \"SUCCESS\",\n \"type\": \"STANDALONE\",\n \"application_interaction_id\": \"<string>\",\n \"application_variant_id\": \"<string>\",\n \"expected\": {},\n \"obs_trace_id\": \"<string>\",\n \"obs_span_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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>",
"obs_trace_id": "<string>",
"obs_span_id": "<string>",
"input_tokens": 2147483647,
"output_tokens": 2147483647
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"detail": "<string>"
}Authorizations
Headers
Body
id for grouping traces together, uuid is recommended
256When the span started. With trace_id and id it forms the span's storage identity, so a span re-sent with a start_timestamp on another UTC day is stored as a second row that the store never collapses. Get span and trace detail return the newest version. Search returns the newest version whose start_timestamp falls in the queried window. Export, metrics and facets count both rows until the trace is deleted and re-sent.
The id of the span, at most 256 bytes. A value longer than 256 characters is refused here with a 422 before it is forwarded; a value within that count whose UTF-8 form exceeds 256 bytes is refused with a 400 naming the field once the tracing service is the account's primary store, and accepted for accounts still written primarily to the legacy trace store.
256Reference to a parent span_id
Reference to a group_id, at most 256 bytes. A value longer than 256 characters is refused here with a 422 before it is forwarded; a value within that count whose UTF-8 form exceeds 256 bytes is refused with a 400 naming the field once the tracing service is the account's primary store, and accepted for accounts still written primarily to the legacy trace store.
256SUCCESS, ERROR, CANCELED 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 The optional application interaction ID this span belongs to
The optional application variant ID this span belongs to
W3C trace id (32 lowercase hex chars) of the observability trace this span executed in, for correlating a business span with the infrastructure work it caused. Stored only by the sgp-traces service, so accounts still served by the legacy store accept the field and read it back as null.
W3C span id (16 lowercase hex chars) of the observability span this span executed in. Requires obs_trace_id.
Response
Successful Response
id for grouping traces together, uuid is recommended
256"span"The identity that created the entity.
Show child attributes
Show child attributes
Reference to a parent span_id
Reference to a group_id
SUCCESS, ERROR, CANCELED 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 The interaction ID this span belongs to
The id of the application variant this span belongs to
W3C trace id of the observability trace this span executed in. Null for spans written without the edge, and for accounts still served by the legacy trace store.
W3C span id of the observability span this span executed in.
Prompt tokens the producer reported for this span, absent when it reported none. Same quantity the input_tokens sort orders by.
0 <= x <= 4294967295Completion tokens the producer reported for this span, absent when it reported none. Same quantity the output_tokens sort orders by.
0 <= x <= 4294967295