Tracing

Agent API participates in OpenTelemetry traces. Send a W3C traceparent on any /api/v1 call and the Agent continues that trace, then returns traceresponse so your collector can join the HTTP client span to the server span.

Hosted Agents on Pro and Enterprise can send this Agent’s spans to your own collector. In Console, open Agents → [agent] → API → Observability, turn on Enable OpenTelemetry Export, paste an HTTPS collector URL, and add header name/value pairs if your backend needs auth. Only spans tagged with that Agent’s id are exported. Prompt text is never recorded on spans.

Every plan still gets correlation IDs on the HTTP response and on notification webhooks. Self-hosted Agents can also set OTEL_EXPORTER_OTLP_ENDPOINT for a process-wide collector.

Request Headers

Pass these on any /api/v1 request. Generated SDKs already merge requestOptions.headers, so an instrumented client can forward them as-is.

CORS allows these headers on browser calls.

Response Header

Every /api/v1 response includes traceresponse in the same 00-{trace-id}-{span-id}-{flags} form. When you sent traceparent, the trace id matches yours.

Notification Webhooks

When a notification fires during an instrumented request, the webhook JSON includes:

{
  "trace": {
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "span_id": "00f067aa0ba902b7"
  }
}

Use trace.trace_id to join prompt_submit, response_end, and error events to the API call in your own tooling. See Notifications.

What Is Recorded

Chat completions add child spans for responder routing, RAG, guardrails, and the model call. Span attributes include agent, completion, conversation, and session IDs, model and provider, token counts, and latency.

Prompt text, system instructions, and message bodies are not recorded on spans by default.

Next Step

Review the generated API reference for POST /chat/completions, or continue to Getting Started if you have not planned the rest of the integration.