Traces

The traces endpoint receives OTLP/HTTP exports from server side instrumentation and turns GenAI spans into runs. It accepts an API key on https://backend.assistant-api.com; Aui-Workspace-Id is optional on this route, unlike the other API key routes, and the general host and credential rules are in Conventions.

Export traces

POST /v1/traces

curl https://backend.assistant-api.com/v1/traces \
  -H "Authorization: Bearer $ASSISTANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resourceSpans": [] }'

{
  "resourceSpans": []
}

{}

{
  "partialSuccess": {
    "rejectedSpans": 1,
    "errorMessage": "Trace 0123456789abcdef0123456789abcdef exceeds the 500 span limit"
  }
}

When all spans are accepted, the response is {}. When spans are rejected, partialSuccess contains rejectedSpans and errorMessage; the message joins the per trace errors, or uses <n> spans were rejected when there is no per trace error.

Span mapping

The receiver recognizes the six operation names chat, text_completion, embeddings, execute_tool, invoke_agent and create_agent, read from gen_ai.operation.name or, when that attribute is absent, from the first word of the span name. The first recognized GenAI span without a GenAI ancestor starts the trace's run, later roots of the same trace join it, and every recognized GenAI descendant belongs to that run. A span linked through non GenAI spans is reparented to its nearest GenAI ancestor. Spans without a recognized operation are rejected and counted in partialSuccess.

Stored generation spans become steps, except for generation spans under tool spans, which are sampling spans. The first generation step is initial; later generation steps are tool-result when a tool ran between the previous and current generation, otherwise continue. Tool spans without a generation parent are attached to the generation that finished latest before the tool began.

Receiver attributes

The receiver reads these span and resource attributes. Unmapped span attributes remain in the stored span attributes.

Limits and identifiers

Each trace keeps at most 500 spans. Extra spans are rejected and counted in partialSuccess with Trace <id> exceeds the 500 span limit. Run attributes and span attributes are each capped at 16,384 bytes. When a cap is exceeded, the receiver drops the largest entries first and adds truncated: true.

The run id is deterministic: run_<sha256(projectId+traceId+rootSpanId) first 24 hex>. A span's primary key is <traceId><spanId>, and spans upsert on (project_id, trace_id, span_id), replacing every span column with the exported value. An existing run with the same (project_id, trace_id) is locked and updated, and the daily run rollup removes the previous values before applying the new ones.

Re export and client reports

Re exporting a trace keeps the client owned source, created_by, created_at, thread_id, assistant_id, message_id, tags, environment, release and first_token_ms, as well as aborted and disconnected outcomes. Existing attributes whose key starts with client. always win. A client report with the same trace id merges into the existing run under these rules; the full field mapping is in Traces.

The route inserts runs and spans in a transaction, records the thread run on the first insert that has a thread, recomputes span_index, assigns parents and step types, and updates the daily rollup. A transaction failure for one run rejects that run's spans and adds its message to partialSuccess; other runs in the export continue. Re exporting is idempotent for the deterministic run and span keys, and spans are indexed by start time, then relative start time and id.