> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.apologist.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.apologist.ai/_mcp/server.

# Tracing

> Continue a W3C trace through Agent API requests and stitch notification webhooks

Agent API participates in [OpenTelemetry](https://opentelemetry.io/) 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.

| Header        | Required | Purpose                                                      |
| ------------- | -------- | ------------------------------------------------------------ |
| `traceparent` | No       | W3C Trace Context parent (`00-{trace-id}-{span-id}-{flags}`) |
| `tracestate`  | No       | Vendor list that travels with `traceparent`                  |
| `baggage`     | No       | W3C baggage. Prompt text is never copied onto spans          |

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:

```json
{
  "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](/console/orchestration/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](/agent-api/getting-started) if you have not planned the rest of the integration.