> ## Documentation Index
> Fetch the complete documentation index at: https://docs.protege.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Capture

> What the gateway records per request, where it goes, and how to turn it off.

Capture is what makes everything downstream possible. Without recorded traffic
there is no evidence for a route change and no corpus to train from.

It is decided per [workload](/concepts/projects-and-workloads), with a sample
rate, and it is on by default for a new workload.

## What is recorded

Two layers. Metadata is recorded for every request, whether or not the workload
is capturing:

| Field                                             | Meaning                                         |
| ------------------------------------------------- | ----------------------------------------------- |
| `requestId`                                       | The value returned in `x-request-id`            |
| `projectSlug`, `workloadName`                     | The scope the request was attributed to         |
| `model`                                           | The model that actually served it               |
| `status`, `httpStatus`, `errorCode`               | Outcome, and the failure code when there is one |
| `streamed`                                        | Whether the response was streamed               |
| `promptTokens`, `completionTokens`, `totalTokens` | Usage                                           |
| `cachedTokens`, `cacheHit`                        | Prompt-cache reuse                              |
| `costUsd`                                         | Measured cost of the call                       |
| `ttftMs`                                          | Time to first token on a streamed response      |
| `inputPreview`                                    | A short excerpt of the first user message       |

The full request and response bodies are stored **only when the workload is
capturing and the request falls inside the sample rate**.

<Note>
  Metadata is what powers per-workload cost and latency reporting, so those keep
  working with capture off. What you lose is the ability to replay a candidate
  model against real traffic, which is the evidence a route change needs.
</Note>

## Sampling

The sample rate is a fraction from 0 to 1, applied deterministically per request
ID. The same request is either always captured or never captured; it does not
flip between retries of the same call.

A high-volume workload rarely needs everything. What matters is coverage of the
input shapes you actually see, and a 10% sample of a million calls has that.

## Turning it off

Set capture off for the workload. Metadata continues; bodies stop.

<Warning>
  The setting is cached on the request path, so a toggle can take up to 60
  seconds to take effect. It is a recording switch, not a kill switch. If you
  need a hard guarantee for a specific call, do not send it through a capturing
  workload in the first place.
</Warning>

If the settings store is unreachable the gateway fails **capture-on**. Losing
traces silently is the worse outcome, because you cannot tell afterwards that
they were lost.

## What it is used for

<CardGroup cols={2}>
  <Card title="Cost per workload" icon="chart-column" href="/concepts/projects-and-workloads">
    Which call sites actually spend the money, which is rarely the one people guess.
  </Card>

  <Card title="Routing evidence" icon="route" href="/concepts/routing">
    Candidate models are replayed against captures, not against your live traffic.
  </Card>

  <Card title="Failures" icon="gavel" href="/concepts/failures">
    The calls that went wrong, which is what a training run needs.
  </Card>

  <Card title="Training corpus" icon="graduation-cap" href="/concepts/failures">
    A workload that cannot route down becomes a candidate for its own model.
  </Card>
</CardGroup>