Traces - Belvedir

POST /api/v1/traces receives OpenTelemetry trace data over OTLP/HTTP. The SDK calls it for you, and any stock OpenTelemetry exporter can target it too (see Agents without the SDK).

Request

Body: an OTLP ExportTraceServiceRequest, either JSON (Content-Type: application/json, a resourceSpans array) or protobuf (Content-Type: application/x-protobuf or application/protobuf). Content-Encoding: gzip is accepted.
Optional header x-belvedir-session-from: trace: spans without a session id get their trace id as the session. Only traces that contain an LLM call become sessions, and only when the LLM span is in the same request, so keep a trace’s spans in one export.

Spans tagged with a session id (withSession in the SDK, or a session.id / gen_ai.conversation.id span attribute from other exporters) are grouped into sessions and segmented into tasks; untagged spans still land but are not linked or segmented.

Errors and limits

Limit	Value
Request body	5 MB, raw or after gzip inflation; `413` beyond it
Spans per request	1,000; `400` beyond it
Distinct sessions per request	200; `400` beyond it
Rate	2 requests per second sustained per key, burst 120; separately, 20 new session ids per second, burst 2,000. `429` with `Retry-After` beyond either

A 402 means the project has no organization to bill to; create or join one for the project. Trace ingestion itself is not billed.