Skip to main content
POST
https://api.respan.ai
/
api
/
v2
/
traces
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.respan.ai/api/v2/traces",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("my-operation") as span:
    span.set_attribute("gen_ai.request.model", "gpt-4")
    span.set_attribute("respan.customer.identifier", "user_123")

{
  "partialSuccess": {
    "rejectedSpans": 0,
    "errorMessage": ""
  }
}
Send traces to Respan using the standard OTLP/HTTP protocol. Any OpenTelemetry-compatible SDK can export directly to this endpoint.
For the easiest setup, use the Respan tracing SDK or the OpenTelemetry integration which auto-configures the exporter. This endpoint is for direct OTLP/HTTP access.

​
Authentication

Authorization: Bearer YOUR_API_KEY

​
Content types

Content-TypeFormatDescription
application/jsonOTLP/HTTP JSONStandard OTLP JSON encoding
application/x-protobufOTLP/HTTP ProtobufBinary protobuf encoding (ExportTraceServiceRequest)

​
Body

The request body follows the standard OTLP ExportTraceServiceRequest schema.
​
resourceSpans
array
required
Array of resource spans. Each element represents spans from a single resource (service).
​
resource
object
Resource metadata for the spans.
​
attributes
array
Key-value attributes identifying the resource. Set service.name to identify your application.
​
scopeSpans
array
required
Array of instrumentation scope spans.
​
scope
object
Instrumentation scope metadata (library name and version).
​
spans
array
required
Array of span objects.
​
traceId
string
required
Hex-encoded trace identifier (16 bytes / 32 hex chars).
​
spanId
string
required
Hex-encoded span identifier (8 bytes / 16 hex chars).
​
parentSpanId
string
Hex-encoded parent span ID. Empty for root spans.
​
name
string
required
Name of the span operation.
​
startTimeUnixNano
string
required
Start time as nanoseconds since Unix epoch (string).
​
endTimeUnixNano
string
required
End time as nanoseconds since Unix epoch (string).
​
status
object
Span status. code: 1 (OK) or 2 (ERROR). message: error description.
​
attributes
array
Span attributes as key-value pairs. See Recognized attributes below.
​
events
array
Span events (e.g., exceptions). Each event has name, timeUnixNano, and attributes.

​
Recognized attributes

​
Gen AI semantic conventions

Attribute keyDescription
gen_ai.request.modelRequested model name
gen_ai.response.modelModel that actually responded
gen_ai.request.temperatureTemperature setting
gen_ai.request.max_tokensMax token limit
gen_ai.usage.prompt_tokensInput token count
gen_ai.usage.completion_tokensOutput token count
gen_ai.usage.total_tokensTotal token count
gen_ai.prompt.{N}.roleMessage role (user, assistant, system)
gen_ai.prompt.{N}.contentMessage content
gen_ai.completion.{N}.roleResponse role
gen_ai.completion.{N}.contentResponse content

​
Respan extensions

Attribute keyDescription
respan.customer.identifierCustomer/user identifier for filtering
respan.customer.emailCustomer email
respan.customer.nameCustomer display name
respan.thread.idThread/conversation identifier
respan.trace_group.idTrace group for linking related traces
respan.metadataJSON object merged into span metadata
respan.entity.log_typeExplicit span type override
All other attributes are stored in the span’s metadata and are queryable via the metadata filter in the Respan UI.

​
OTLP value types

Attribute values are wrapped in typed objects per the OTLP spec:
Wrapper keyTypeExample
stringValuestring{"stringValue": "hello"}
intValueint{"intValue": "42"}
doubleValuefloat{"doubleValue": 3.14}
boolValuebool{"boolValue": true}
arrayValuelist{"arrayValue": {"values": [...]}}
kvlistValuedict{"kvlistValue": {"values": [{"key": "k", "value": {...}}]}}
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.respan.ai/api/v2/traces",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("my-operation") as span:
    span.set_attribute("gen_ai.request.model", "gpt-4")
    span.set_attribute("respan.customer.identifier", "user_123")

{
  "partialSuccess": {
    "rejectedSpans": 0,
    "errorMessage": ""
  }
}

​
Response fields

FieldTypeDescription
partialSuccess.rejectedSpansintegerNumber of spans that failed to ingest
partialSuccess.errorMessagestringError description (empty on success)

​
Error responses

CodeDescription
200 OKAll spans accepted
400 Bad RequestMalformed payload
401 UnauthorizedInvalid or missing API key