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

# Metadata and traces

> Select a project version, preserve conversation identity, and attach searchable context.

Include proxy controls and trace attributes in the standard Chat Completions `metadata` object. This page explains how to preserve conversation identity, sample complete conversations, and understand the resulting project traces.

The OpenAI SDKs accept `metadata` as a built-in request parameter, so you don't need `extra_body`. Older releases of the `openai` Python package that don't have the `metadata` parameter still need `extra_body={"metadata": {...}}`.

## Reserved metadata

| Key | Type | Purpose |
| - | - | - |
| `gen_ai.conversation.id` | non-empty `string` | Conversation identifier for sticky routing, conversation sampling, and conversation grouping in W\&B Weave |
| `forge.project_version` | `string` such as `"2"`, or `integer` | Select a project version. Requires the `OpenAI-Project` header. Omit it for version 1 |
| `forge.turn_index` | non-negative `integer` | Preserve a trusted source turn index during replay |
| `user.id` | non-empty `string` | Attach an end-user identity to the trace |
| `forge.call_shadow` | `boolean` | Also log a Weave Call beside the Agent Span for a project-routed request, which duplicates trace storage |

`forge.*` and `wandb.*` keys are reserved for proxy controls. The proxy removes them before it sends a request to the provider, and it doesn't record them as custom trace attributes. The proxy forwards other metadata to the provider. When representable, the proxy also adds that metadata to the trace.

Don't use your own metadata keys that start with `forge.` or `wandb.`. The proxy treats them as controls.

The trace also doesn't record custom metadata that reuses a name the proxy records itself, such as `routing_mode`, `task_version`, or `alias`. Agent Spans also skip `error.type` and `gen_ai.*` keys other than `gen_ai.conversation.id`. The proxy still forwards these keys to the provider.

## Conversation precedence

Send the conversation identifier as `gen_ai.conversation.id`, the OpenTelemetry name. The proxy chooses the first available identifier:

1. `gen_ai.conversation.id`
2. Vapi `call.id`

Use the same value for every provider call in a conversation in your application. This improves browsing traces, prevents one conversation from spanning multiple dataset splits, and makes weighted routing stable. The conversation identifier doesn't change the [response cache](https://docs.coreweave.com/model-distillation/proxy/response-caching.md) key.

## Sample complete conversations

Conversation-level trace sampling reduces the volume of project traffic saved to Weave without leaving partial conversations. Per-request sampling can keep isolated turns and discard the surrounding context, which makes the saved data less useful for debugging and dataset creation.

To configure sampling for a project:

1. In Model Distillation, open the project's **Routing** page.
2. Under **Models and traffic**, set **Weave trace sampling** to the percentage of conversations to save.
3. Select **Save routing**.

After you save the routing configuration, the proxy uses the selected percentage for conversation-level trace sampling.

For requests with a conversation identity, the proxy assigns the conversation to a stable sampling group based on the Weights & Biases entity, Model Distillation project, and conversation ID. The default sampling rate is 100 percent. The proxy either saves or skips every request with that identity. The sampling decision is independent of model selection and routing revisions. Skipped traces don't prevent the proxy from serving inference responses.

The proxy always saves requests without a conversation identity. Keep the sampling percentage stable for the lifetime of active conversations because a change can affect which conversations are saved.

> [accordion] API: Set conversation trace sampling (PUT /projects/\[PROJECT-ALIAS]/routing)
>
> To configure conversation-level trace sampling without Model Distillation, use the routing API.
>
> Replace `[PROJECT-ALIAS]` with the project alias, `[WANDB-ENTITY]` with the Weights & Biases entity, and `[MODEL-REF]` with an existing target model reference.
>
> Set `trace_sampling_rate` to a fraction from `0` to `1`. Because a routing update replaces the complete configuration, include all existing targets in the request:
>
> ```bash theme={"system"}
> curl --request PUT \
>   --url "https://forge.coreweave.com/api/distillation/v1/projects/[PROJECT-ALIAS]/routing" \
>   --header "Authorization: Bearer $WANDB_API_KEY" \
>   --header "Forge-Entity: [WANDB-ENTITY]" \
>   --header "Content-Type: application/json" \
>   --data '{
>     "trace_sampling_rate": 0.1,
>     "targets": [
>       {"model_ref": "[MODEL-REF]", "weight": 1}
>     ]
>   }'
> ```
>
> For another project version, use `PUT /v1/projects/[PROJECT-ALIAS]/versions/[PROJECT-VERSION]/routing`. Replace `[PROJECT-ALIAS]` with the project alias and `[PROJECT-VERSION]` with the project version. Before you treat the setting as active, wait until the deployment status is **Applied** at the new routing revision.

## Project trace contents

Project traces capture the following routing, request, response, and metadata details:

* Project ID (UUID), project alias, and version.
* Routing revision and selected provider and model.
* The routing mode (`routing_mode`): `weighted` when the proxy selected a target, or `override` when the request named a `provider/model` [model override](https://docs.coreweave.com/model-distillation/proxy/model-routing.md).
* The exact request that the proxy sends to the provider and the response that the proxy reconstructs.
* Token usage, finish reason, timing, and error status.
* Whether the response was replayed from the [exact-response cache](https://docs.coreweave.com/model-distillation/proxy/response-caching.md) (`cache_hit`).
* Conversation, user, scenario, and safe custom metadata.
* A proxy request ID for support and comparison of trace outputs.

The canonical Agent Span contains a raw copy of the request and response to preserve details. Dataset reconstruction doesn't rely only on the normalized display columns.

The proxy writes one Agent Span for each project request. Weave's **Agents** view groups these spans into conversations by `gen_ai.conversation.id`. Weave's **Threads** view reads only Calls, so project traffic appears there only for requests that also log a Call with `forge.call_shadow`.

Model overrides are project traffic, so datasets built from project traces can include them. To exclude overrides from a dataset, filter on `metadata: {"routing_mode": "weighted"}`. This filter also excludes traces written before the proxy began recording `routing_mode`.

> [!WARNING]
>
> Don't put credentials, secrets, or unnecessary personal data in messages or metadata. Trace data is intentionally durable training and debugging input.

> [accordion] API: Send a request with conversation identity (POST /chat/completions)
>
> Replace `[WANDB-ENTITY]` with the Weights & Biases entity, `[WANDB-PROJECT]` with the project's Weights & Biases project name (not its alias), and `[CONVERSATION-ID]` with an identifier for the conversation.
>
> Keep the same `gen_ai.conversation.id` for every turn in one conversation:
>
> ```bash theme={"system"}
> curl --request POST \
>   --url "https://proxy.training.coreweave.com/v1/chat/completions" \
>   --header "Authorization: Bearer $WANDB_API_KEY" \
>   --header "OpenAI-Project: [WANDB-ENTITY]/[WANDB-PROJECT]" \
>   --header "Content-Type: application/json" \
>   --data '{
>     "model": "router",
>     "messages": [{"role": "user", "content": "Classify this request"}],
>     "metadata": {
>       "gen_ai.conversation.id": "[CONVERSATION-ID]"
>     }
>   }'
> ```
>
> To pin a version other than version 1, add `"forge.project_version": "2"` to `metadata`. The proxy removes reserved `forge.*` values before sending a request to the provider. See [Create a routed chat completion](https://docs.coreweave.com/model-distillation/reference/proxy/chat-completions/create-a-routed-chat-completion.md).
