# Response headers

> Every x-agent-stream-* response header a surface can return, and whether it appears on a buffered or a streamed response.

Every x-agent-stream-* header below is the exact header name Agent Stream sends, not a paraphrase. A client can read cost and usage figures directly from these headers without parsing the response body.

## Every-request headers

Built once per completed LLM-surface execution and attached to the response.

| Header | Meaning | Buffered | Streamed |
| x-agent-stream-trace-id | Request trace id. | Yes | Yes |
| x-agent-stream-provider | Upstream provider that served the call. | Yes | Yes |
| x-agent-stream-model | Model identifier. | Yes | Yes |
| x-agent-stream-cache | Cache status: hit or miss. | Yes | Yes (always miss, a stream is never served from cache) |
| x-agent-stream-input-tokens | Input tokens for the execution. | Yes | No |
| x-agent-stream-output-tokens | Output tokens for the execution. | Yes | No |
| x-agent-stream-total-tokens | Total tokens for the execution. | Yes | No |
| x-agent-stream-cached-tokens | Provider-side cached input tokens. | Yes | No |
| x-agent-stream-cache-write-tokens | Provider-side cache-write tokens. | Yes | No |
| x-agent-stream-reasoning-tokens | Reasoning tokens, for a reasoning-capable model. | Yes | No |
| x-agent-stream-cost-usd | USD cost for the execution, to 6 decimal places. | Yes | No |
| x-agent-stream-cache-saved-usd | Provider spend avoided by a cache hit. Present only on a cache-hit response. | Only on a cache hit | No |

A streamed response is returned before the completion (and so its tokens/cost) is known, so it carries only the request-time subset (trace id, provider, model, and a fixed cache: miss) set at stream start, not the token/cost/cache-saved fields above.

## Conditional headers

Present only when the surface used the corresponding feature for this request; absent otherwise.

| Header | Meaning | Present when |
| x-agent-stream-schema-valid | Whether the response conformed to the requested structured-output schema. | The request asked for a structured output. |
| x-agent-stream-context-transform | Which context-window compression strategy ran. | Context-window compression fired for this request. |
| x-agent-stream-documents | Document-ingestion summary for the request. | The request included ingested documents. |
| x-agent-stream-audio | Audio-input handling summary for the request. | The request included audio input. |
| x-agent-stream-images | Image-input handling summary for the request. | The request included image input. |

## Negotiated dialect

| Header | Meaning | Buffered | Streamed |
| x-agent-stream-ingress-skin | The negotiated client dialect (openai_chat, anthropic_messages, openai_responses), set on the outer response regardless of success/error/stream. | Yes | Yes |

## API-pipe conversation header

| Header | Meaning | Present when |
| x-agent-stream-conversation-id | Server-assigned conversation id for an API-type surface, so the client can send it back on the next turn. | The surface is an API pipe (not an LLM chat surface) and assigned a conversation id. |

## Inbound-only headers

These are headers a caller sends, not response headers: listed here because they share the x-agent-stream-* / X-Agent-Stream-* prefix and are easy to mistake for response headers.

| Header | Meaning |
| X-Agent-Stream-Presentation (configurable name) | Default header name a caller uses to present verifiable-presentation (VP) evidence, when a surface’s VP evidence source is header. |
| X-Agent-Stream-Upstream-Authorization | Lets a caller supply a distinct upstream credential (e.g. a Microsoft Graph token for Copilot) alongside the front-door token, separate from the surface’s own configured provider auth. |

## Related

- [Telemetry and exports](/products/affinidi-trust-fabric/agent-stream/reference/observability/telemetry-and-exports.md): The per-request telemetry record these headers are derived from.

- [Observability concept](/products/affinidi-trust-fabric/agent-stream/concepts/observability.md): Why these figures are exposed on the response rather than only in the dashboard.

- [Server tools and modalities](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/server-tools-and-modalities.md): The document/audio/image ingestion and context-compression features the conditional headers report on.

- [Providers](/products/affinidi-trust-fabric/agent-stream/reference/surfaces/providers.md): Upstream provider auth, including the upstream-authorization override header.