Metadata and traces - CoreWeave Docs

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:

gen_ai.conversation.id
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 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:

In Model Distillation, open the project’s Routing page.
Under Models and traffic, set Weave trace sampling to the percentage of conversations to save.
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.

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:

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.
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 (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.

Don’t put credentials, secrets, or unnecessary personal data in messages or metadata. Trace data is intentionally durable training and debugging input.

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:

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.