Export OTLP traces
curl --request POST \
--url https://api.zespan.com/v1/traces \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"resourceSpans": [
{
"resource": {
"attributes": [
{
"key": "gen_ai.system",
"value": {}
}
]
},
"scopeSpans": [
{
"scope": {
"name": "<string>",
"version": "<string>"
},
"spans": [
{
"traceId": "<string>",
"spanId": "<string>",
"name": "chat.completions",
"startTimeUnixNano": "1751716800000000000",
"parentSpanId": "<string>",
"kind": 123,
"endTimeUnixNano": "<string>",
"attributes": [
{
"key": "gen_ai.system",
"value": {}
}
],
"status": {
"code": 123,
"message": "<string>"
}
}
]
}
]
}
]
}
'import requests
url = "https://api.zespan.com/v1/traces"
payload = { "resourceSpans": [
{
"resource": { "attributes": [
{
"key": "gen_ai.system",
"value": {}
}
] },
"scopeSpans": [
{
"scope": {
"name": "<string>",
"version": "<string>"
},
"spans": [
{
"traceId": "<string>",
"spanId": "<string>",
"name": "chat.completions",
"startTimeUnixNano": "1751716800000000000",
"parentSpanId": "<string>",
"kind": 123,
"endTimeUnixNano": "<string>",
"attributes": [
{
"key": "gen_ai.system",
"value": {}
}
],
"status": {
"code": 123,
"message": "<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({
resourceSpans: [
{
resource: {attributes: [{key: 'gen_ai.system', value: {}}]},
scopeSpans: [
{
scope: {name: '<string>', version: '<string>'},
spans: [
{
traceId: '<string>',
spanId: '<string>',
name: 'chat.completions',
startTimeUnixNano: '1751716800000000000',
parentSpanId: '<string>',
kind: 123,
endTimeUnixNano: '<string>',
attributes: [{key: 'gen_ai.system', value: {}}],
status: {code: 123, message: '<string>'}
}
]
}
]
}
]
})
};
fetch('https://api.zespan.com/v1/traces', 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.zespan.com/v1/traces",
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([
'resourceSpans' => [
[
'resource' => [
'attributes' => [
[
'key' => 'gen_ai.system',
'value' => [
]
]
]
],
'scopeSpans' => [
[
'scope' => [
'name' => '<string>',
'version' => '<string>'
],
'spans' => [
[
'traceId' => '<string>',
'spanId' => '<string>',
'name' => 'chat.completions',
'startTimeUnixNano' => '1751716800000000000',
'parentSpanId' => '<string>',
'kind' => 123,
'endTimeUnixNano' => '<string>',
'attributes' => [
[
'key' => 'gen_ai.system',
'value' => [
]
]
],
'status' => [
'code' => 123,
'message' => '<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.zespan.com/v1/traces"
payload := strings.NewReader("{\n \"resourceSpans\": [\n {\n \"resource\": {\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ]\n },\n \"scopeSpans\": [\n {\n \"scope\": {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"spans\": [\n {\n \"traceId\": \"<string>\",\n \"spanId\": \"<string>\",\n \"name\": \"chat.completions\",\n \"startTimeUnixNano\": \"1751716800000000000\",\n \"parentSpanId\": \"<string>\",\n \"kind\": 123,\n \"endTimeUnixNano\": \"<string>\",\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ],\n \"status\": {\n \"code\": 123,\n \"message\": \"<string>\"\n }\n }\n ]\n }\n ]\n }\n ]\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.zespan.com/v1/traces")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"resourceSpans\": [\n {\n \"resource\": {\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ]\n },\n \"scopeSpans\": [\n {\n \"scope\": {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"spans\": [\n {\n \"traceId\": \"<string>\",\n \"spanId\": \"<string>\",\n \"name\": \"chat.completions\",\n \"startTimeUnixNano\": \"1751716800000000000\",\n \"parentSpanId\": \"<string>\",\n \"kind\": 123,\n \"endTimeUnixNano\": \"<string>\",\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ],\n \"status\": {\n \"code\": 123,\n \"message\": \"<string>\"\n }\n }\n ]\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zespan.com/v1/traces")
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 \"resourceSpans\": [\n {\n \"resource\": {\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ]\n },\n \"scopeSpans\": [\n {\n \"scope\": {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"spans\": [\n {\n \"traceId\": \"<string>\",\n \"spanId\": \"<string>\",\n \"name\": \"chat.completions\",\n \"startTimeUnixNano\": \"1751716800000000000\",\n \"parentSpanId\": \"<string>\",\n \"kind\": 123,\n \"endTimeUnixNano\": \"<string>\",\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ],\n \"status\": {\n \"code\": 123,\n \"message\": \"<string>\"\n }\n }\n ]\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"partialSuccess": {
"rejectedSpans": 0,
"errorMessage": ""
}
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}Export OTLP traces
OTLP-compatible trace export endpoint. Accepts an ExportTraceServiceRequest payload as JSON (application/json) or protobuf (application/x-protobuf). Spans are converted to Zespan events and queued asynchronously.
Authenticated with x-api-key, or with Authorization: Bearer zsp_... (the same project key). Rate limited to 3,000 requests/minute per project by default (429 with Retry-After over it), capped at 8 MiB (measured after decompression; gzip request bodies are accepted; 413, which exporters do not retry, over it) and 512 spans per request, and counted against the organization’s monthly event quota. These limits are for this endpoint only; /v1/ingest keeps its own.
Success is 200. Spans that could not be stored (more than 512 in one request, unusable trace or span ids, no valid start time) are counted in partialSuccess.rejectedSpans with a reason in errorMessage; exporters do not retry those. A protobuf request is answered with a protobuf ExportTraceServiceResponse, a JSON request with JSON. JSON span kind and status.code may be numbers or enum names, and ids may be hex or base64.
POST
/
v1
/
traces
Export OTLP traces
curl --request POST \
--url https://api.zespan.com/v1/traces \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"resourceSpans": [
{
"resource": {
"attributes": [
{
"key": "gen_ai.system",
"value": {}
}
]
},
"scopeSpans": [
{
"scope": {
"name": "<string>",
"version": "<string>"
},
"spans": [
{
"traceId": "<string>",
"spanId": "<string>",
"name": "chat.completions",
"startTimeUnixNano": "1751716800000000000",
"parentSpanId": "<string>",
"kind": 123,
"endTimeUnixNano": "<string>",
"attributes": [
{
"key": "gen_ai.system",
"value": {}
}
],
"status": {
"code": 123,
"message": "<string>"
}
}
]
}
]
}
]
}
'import requests
url = "https://api.zespan.com/v1/traces"
payload = { "resourceSpans": [
{
"resource": { "attributes": [
{
"key": "gen_ai.system",
"value": {}
}
] },
"scopeSpans": [
{
"scope": {
"name": "<string>",
"version": "<string>"
},
"spans": [
{
"traceId": "<string>",
"spanId": "<string>",
"name": "chat.completions",
"startTimeUnixNano": "1751716800000000000",
"parentSpanId": "<string>",
"kind": 123,
"endTimeUnixNano": "<string>",
"attributes": [
{
"key": "gen_ai.system",
"value": {}
}
],
"status": {
"code": 123,
"message": "<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({
resourceSpans: [
{
resource: {attributes: [{key: 'gen_ai.system', value: {}}]},
scopeSpans: [
{
scope: {name: '<string>', version: '<string>'},
spans: [
{
traceId: '<string>',
spanId: '<string>',
name: 'chat.completions',
startTimeUnixNano: '1751716800000000000',
parentSpanId: '<string>',
kind: 123,
endTimeUnixNano: '<string>',
attributes: [{key: 'gen_ai.system', value: {}}],
status: {code: 123, message: '<string>'}
}
]
}
]
}
]
})
};
fetch('https://api.zespan.com/v1/traces', 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.zespan.com/v1/traces",
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([
'resourceSpans' => [
[
'resource' => [
'attributes' => [
[
'key' => 'gen_ai.system',
'value' => [
]
]
]
],
'scopeSpans' => [
[
'scope' => [
'name' => '<string>',
'version' => '<string>'
],
'spans' => [
[
'traceId' => '<string>',
'spanId' => '<string>',
'name' => 'chat.completions',
'startTimeUnixNano' => '1751716800000000000',
'parentSpanId' => '<string>',
'kind' => 123,
'endTimeUnixNano' => '<string>',
'attributes' => [
[
'key' => 'gen_ai.system',
'value' => [
]
]
],
'status' => [
'code' => 123,
'message' => '<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.zespan.com/v1/traces"
payload := strings.NewReader("{\n \"resourceSpans\": [\n {\n \"resource\": {\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ]\n },\n \"scopeSpans\": [\n {\n \"scope\": {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"spans\": [\n {\n \"traceId\": \"<string>\",\n \"spanId\": \"<string>\",\n \"name\": \"chat.completions\",\n \"startTimeUnixNano\": \"1751716800000000000\",\n \"parentSpanId\": \"<string>\",\n \"kind\": 123,\n \"endTimeUnixNano\": \"<string>\",\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ],\n \"status\": {\n \"code\": 123,\n \"message\": \"<string>\"\n }\n }\n ]\n }\n ]\n }\n ]\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.zespan.com/v1/traces")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"resourceSpans\": [\n {\n \"resource\": {\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ]\n },\n \"scopeSpans\": [\n {\n \"scope\": {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"spans\": [\n {\n \"traceId\": \"<string>\",\n \"spanId\": \"<string>\",\n \"name\": \"chat.completions\",\n \"startTimeUnixNano\": \"1751716800000000000\",\n \"parentSpanId\": \"<string>\",\n \"kind\": 123,\n \"endTimeUnixNano\": \"<string>\",\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ],\n \"status\": {\n \"code\": 123,\n \"message\": \"<string>\"\n }\n }\n ]\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zespan.com/v1/traces")
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 \"resourceSpans\": [\n {\n \"resource\": {\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ]\n },\n \"scopeSpans\": [\n {\n \"scope\": {\n \"name\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"spans\": [\n {\n \"traceId\": \"<string>\",\n \"spanId\": \"<string>\",\n \"name\": \"chat.completions\",\n \"startTimeUnixNano\": \"1751716800000000000\",\n \"parentSpanId\": \"<string>\",\n \"kind\": 123,\n \"endTimeUnixNano\": \"<string>\",\n \"attributes\": [\n {\n \"key\": \"gen_ai.system\",\n \"value\": {}\n }\n ],\n \"status\": {\n \"code\": 123,\n \"message\": \"<string>\"\n }\n }\n ]\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"partialSuccess": {
"rejectedSpans": 0,
"errorMessage": ""
}
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}{
"error": "Unauthorized",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"requestId": "5f0c9a4e-3b1d-4e7a-9c2f-8d6b1a0e7c34",
"details": "<unknown>"
}Authorizations
Project API key. Manage keys in the Zespan dashboard under project settings.
Body
application/jsonapplication/x-protobuf
OTLP ExportTraceServiceRequest (JSON encoding).
Show child attributes
Show child attributes
Response
Request accepted. Check partialSuccess.rejectedSpans: spans counted there were not stored.
Show child attributes
Show child attributes
Was this page helpful?