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

> ## Agent Instructions
> If the person you are helping needs a new Vantage account, read https://docs.vantage.sh/auth.md before you register one.

# Bifrost Enrichment

> Attribute LLM spend to teams, users, applications, and features by exporting OpenTelemetry traces from your Bifrost gateway to Vantage, which joins per-request token usage to your provider costs.

> [!NOTE]
>
> Contact Sales (or [support@vantage.sh](mailto:support@vantage.sh)/your account team) to enable LLM Enrichment for your account and discuss availability.

Vantage reads per-request token usage from your [Bifrost](https://docs.getbifrost.ai/) AI gateway and joins it to your model-provider costs. Bifrost's built-in **OpenTelemetry plugin** exports a trace for each request (the upstream provider, model, token counts, virtual key, and the dimensions you attach) directly to a Vantage ingest endpoint. Vantage splits each matching cost row into enriched rows by token share and adds tags derived from that usage, so you can filter and group that spend in [Cost Reports](https://docs.vantage.sh/cost_reports.md), [Virtual Tags](https://docs.vantage.sh/tagging.md), [Budgets](https://docs.vantage.sh/budgets.md), and [Cost Alerts](https://docs.vantage.sh/cost_alerts.md). Because the telemetry comes from your gateway, this surfaces attribution the provider bill never itemized, even when many applications share one provider API key.

Bifrost is the source of usage and attribution, not of cost. Your provider cost integrations remain the financial source of truth: enrichment reattributes the costs they report and never creates, removes, or reprices them.

Bifrost Enrichment attributes costs for the model providers your gateway routes to and that you have connected as Vantage cost integrations: **OpenAI**, **Anthropic** (Claude API or Claude.ai), **AWS Bedrock**, **Google Cloud** (Vertex AI Gemini and Marketplace Claude), **Azure**, **SpaceXAI**, **Baseten**, **Modal**, and **Together AI**. Vantage automatically routes each usage record to the matching provider's costs.

The following aren't supported through Bifrost:

* **OpenRouter**
* **Fireworks:** the Fireworks bill doesn't break down by key or user, and lists models by display name.
* **Azure CSP:** only direct Azure billing is supported.

> [!NOTE]
>
> Unlike [Custom LLM Enrichment](https://docs.vantage.sh/custom_llm_enrichment.md) and [AWS Bedrock LLM Enrichment](https://docs.vantage.sh/aws_bedrock_enrichment.md), which read logs you deliver to an S3 bucket you own, Bifrost Enrichment receives traces that Bifrost pushes straight to Vantage. There is no S3 bucket to create, no AWS role to grant, and no collector to run.

Enrichment is metadata-only. Vantage uses the provider, model, token counts, and the attribution fields on each trace. Set `disable_content_logging` to `true` in the Bifrost OpenTelemetry configuration, as shown in [Step 2](#step-2-configure-opentelemetry-on-bifrost), so Bifrost does not export prompt or completion content. This data is not used to train any models.

## How It Works

Bifrost's OpenTelemetry plugin sends trace spans for each request to `https://ingest.vantage.sh/v1/traces`, authenticated with an ingest token you create in Vantage. Vantage stores the spans, builds a daily usage index for each provider from them, and joins that usage to your provider costs during each provider's cost ingestion.

See [How LLM Enrichment works](https://docs.vantage.sh/llm_enrichment.md#how-it-works) for the shared indexing, join, split, and tag pipeline.

### How Bifrost Usage Is Matched to Your Bill

Map your Bifrost provider keys to your provider API keys for exact attribution. With a key mapping, a Bifrost key's usage is tagged only on the cost rows for that API key. Unmapped usage is matched by day, model, and token type (input, output, cache read, and cache write) within each cost integration you select in [Step 3](#step-3-configure-cost-integrations).

Key mappings are available for **OpenAI** and **Anthropic** (Claude API) keys, and you manage them yourself in [Step 4](#step-4-configure-key-mappings). Azure OpenAI and Google Cloud Vertex AI bills don't break down by API key, so their usage is always matched by day, model, and token type. AWS Bedrock usage is matched to the AWS account each Bifrost deployment declares; see [AWS Bedrock Usage Through Bifrost](#aws-bedrock-usage-through-bifrost).

Tags from Bifrost apply only to usage that went through Bifrost. If you also call your provider directly with the same API key, that usage still appears on your bill under the key, but without Bifrost's tags. To tag all of a key's spend, send all of its traffic through Bifrost, or use a separate key for traffic outside Bifrost.

#### Claude Code Usage Through Bifrost

When developers sign in to Claude Code with their Anthropic account (OAuth) and route it through Bifrost, Vantage attributes that usage to each user. On a **Claude.ai** (Anthropic Analytics) cost integration, each user's Bifrost usage is matched by email, case-insensitively, to that user's Claude Code cost rows rather than spread across everyone. Each user's cost rows then carry the virtual key and dimensions from that user's Bifrost requests, alongside the `vntg:ai:user_email` tag the Claude.ai bill already provides. Anthropic usage that Bifrost serves with its own provider key follows the standard matching above.

Per-user matching requires the following:

* You run **Bifrost Enterprise**.
* Each user exists in Bifrost with the same email as their Claude seat, for example provisioned through SSO, SCIM, or directory sync.
* Each user's Claude Code requests carry a Bifrost virtual key assigned to that user, sent in the `x-bf-vk` header alongside their OAuth sign-in.

Claude Code usage that doesn't go through Bifrost stays on that user's cost row without Bifrost's tags. Usage from a user whose email doesn't match a Claude Code cost row is left untagged and appears under **User email scope empty** in the run's [Token Metrics](https://docs.vantage.sh/llm_enrichment_import_history.md#join-dispositions). Its [sample records](https://docs.vantage.sh/llm_enrichment_import_history.md#view-sample-records) list the emails that didn't match.

To route Claude Code through Bifrost, point Claude Code at Bifrost's `/anthropic` route and pass the user's virtual key in a custom header, for example in their Claude Code `settings.json`:

```json settings.json theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://<your-bifrost-host>/anthropic",
    "ANTHROPIC_CUSTOM_HEADERS": "x-bf-vk: sk-bf-<your-virtual-key>"
  }
}
```

Do not also set `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` in this mode, or Claude Code stops using the subscription sign-in. See Bifrost's [Claude Code documentation](https://docs.getbifrost.ai/cli-agents/claude-code) for details.

#### AWS Bedrock Usage Through Bifrost

Bedrock costs come from your [AWS cost integration](https://docs.vantage.sh/connecting_aws.md). To match each Bifrost deployment's Bedrock usage to the right AWS account's cost rows, declare the AWS account on the deployment with the standard OpenTelemetry resource attribute `cloud.account.id`, as shown in [Step 2](#step-2-configure-opentelemetry-on-bifrost). Bifrost attaches the attribute to the traces it exports, and Vantage matches that deployment's Bedrock usage only to Bedrock cost rows for that usage account. This doesn't require an IAM role, an IAM principal on your bill, or CUR 2.0.

When you set `cloud.account.id`, you are declaring which AWS account pays for the deployment's Bedrock requests:

* **Use the account that signs the requests:** Set the 12-digit ID of the AWS account that owns the credentials Bifrost uses to call Bedrock. Don't infer it from an environment name or from the account that hosts the gateway.
* **Vantage uses the value as declared:** Bifrost doesn't discover or verify the account ID. Vantage ignores values that aren't exactly 12 digits.
* **The value covers the whole deployment:** It applies to everything the deployment exports, so all of that deployment's Bedrock traffic must be billed to the declared account.
* **Deployments are independent:** Several deployments can declare the same account, and deployments that send to the same Vantage feed can declare different accounts.
* **Keep it current:** Update the value when the account that signs Bedrock requests changes. A wrong value leaves usage unmatched (**Account scope empty** in Token Metrics) or attributes it to the wrong account.
* **It's for Bedrock only:** Vantage reads `cloud.account.id` only for Bedrock usage. Deployments that don't call Bedrock don't need it.

> [!WARNING]
>
> If one Bifrost deployment calls Bedrock with credentials from more than one AWS account, a single resource attribute can't identify the account for each request. This setup doesn't cover that case. Contact [Vantage Support](mailto:support@vantage.sh) before you enable Bedrock enrichment for that deployment.

If a deployment doesn't declare an account, how Vantage handles its Bedrock usage depends on how many AWS cost integrations you select in [Step 3](#step-3-configure-cost-integrations):

* **One AWS integration:** Vantage spreads the usage across that integration's accounts in proportion to each account's billed Bedrock usage that isn't already covered by usage with a declared account.
* **More than one AWS integration:** Vantage can't tell which integration the usage belongs to, so it withholds the usage rather than guess. It appears as **Ambiguous sibling withheld** in Token Metrics.

Declare an account on every deployment that calls Bedrock for the most accurate attribution. Bedrock rows enriched from Bifrost carry your virtual key and dimension tags, but no `vntg:ai:principal_id` tag.

If you also use [AWS Bedrock LLM Enrichment](https://docs.vantage.sh/aws_bedrock_enrichment.md), don't report the same Bedrock requests through both sources. Your cost isn't double counted, but each source's tags get only part of the matching cost.

### How Cost Rows Are Split

Vantage splits each matching provider cost row into enriched rows, allocated proportionally by token share. Splits are additive, so the enriched rows always reconcile to the original total: usage your logs do not cover stays on a **leftover** row, and cost rows with no matching usage, along with tax line items, pass through unsplit. Enabling enrichment never changes your totals.

> [card] [How Cost Splitting Works](https://docs.vantage.sh/llm_enrichment.md#how-cost-rows-are-split)
>
> See the allocation formula, a worked example, and how leftover rows keep totals reconciled.

### Data Freshness and Backfill

Enrichment runs as part of each provider's existing cost ingestion, so it follows that provider's refresh cadence. Recent days are reprocessed within a rolling three-day window so late-arriving traces are picked up. See the [provider data refresh documentation](https://docs.vantage.sh/provider_data_refresh.md) for per-provider timing.

Enrichment begins from when Bifrost starts exporting traces to Vantage; it does not backfill spend from before the export was running. Re-enrichment reads the already-normalized cost data, so it does not require a full cost re-import.

Traces that Bifrost fails to deliver to Vantage are not retried later, so that usage stays untagged. To catch delivery problems early, alert on Bifrost's `failed to emit trace` log message.

## Prerequisites

Before you begin, make sure:

* An active cost integration exists for at least one supported provider: [OpenAI](https://docs.vantage.sh/connecting_openai.md), [Anthropic](https://docs.vantage.sh/connecting_anthropic.md), [AWS](https://docs.vantage.sh/connecting_aws.md), [Google Cloud](https://docs.vantage.sh/connecting_gcp.md), [Azure](https://docs.vantage.sh/connecting_azure.md), [SpaceXAI](https://docs.vantage.sh/connecting_spacexai.md), [Baseten](https://docs.vantage.sh/connecting_baseten.md), [Modal](https://docs.vantage.sh/connecting_modal.md), or [Together AI](https://docs.vantage.sh/connecting_together_ai.md).
* You run [Bifrost](https://docs.getbifrost.ai/) **v1.5.9 or later**, and can enable its OpenTelemetry plugin (through the Bifrost web UI, `config.json`, or Helm values) and set environment variables. See [Supported Bifrost Versions](#supported-bifrost-versions).
* Your Bifrost deployment has outbound HTTPS access to `ingest.vantage.sh`.
* You have a Vantage **Organization Owner** or **Integration Owner** role. See [Role-Based Access Control](https://docs.vantage.sh/rbac.md).

### Supported Bifrost Versions

Vantage supports Bifrost **v1.5.9 and later**. We recommend **v2.4.0 or later**: earlier versions can occasionally omit token usage from very short streaming responses, which leaves that usage out of Vantage.

| Bifrost version | What to know |
| - | - |
| Before v1.5.9 | Not supported. Older versions use a different span format and can't turn off prompt and response content export (`disable_content_logging`). |
| v1.5.9 to v1.x | Set the authorization header with `headers` instead of `trace_headers`. See [Step 2](#step-2-configure-opentelemetry-on-bifrost). |
| v2.0.0 and later | Use `trace_headers`, as shown in the setup steps. |
| v2.2.6 and later | New deployments require a virtual key on every request by default (`enforce_auth_on_inference`). See [Virtual Keys](#virtual-keys). |

## Set Up Bifrost Enrichment

Setup happens on the feed's **Manage** tab in Vantage. After you connect the source and turn on enrichment, follow the four numbered steps on the tab: [create an ingest token](#step-1-create-the-feed-and-an-ingest-token), [configure OpenTelemetry on Bifrost](#step-2-configure-opentelemetry-on-bifrost), [configure which cost integrations to enrich](#step-3-configure-cost-integrations), and [map your provider keys](#step-4-configure-key-mappings).

### Step 1: Create the Feed and an Ingest Token

**1. Open the Bifrost integration**

In Vantage, go to the [Integrations page](https://console.vantage.sh/settings/integrations). Under **LLM Enrichment**, select **Bifrost**.

**2. Connect the source**

On the **Bifrost** page, select **Connect Source**. Vantage creates a Bifrost feed for your account and opens its **Manage** tab.

**3. Turn on enrichment**

Under **Uses**, select **Enrichment**, then select **Save Uses**. A new feed starts with enrichment turned off: its status shows **Paused**, and you can't configure cost integrations in Step 3 until you turn enrichment on.

**4. Create an ingest token**

Under **Step 1: Manage Ingest Tokens**, optionally enter a name in **Token name (optional)** (up to 100 characters, for example, `Production Bifrost`), then select **Create token**.

**5. Copy the token**

Select **Copy** to copy the token, or **Show** to view it. It starts with `vntg_ti_`.

> [!WARNING]
>
> The full token is shown only once, while you are on the page where you created it. After you leave, the tokens table shows only the last four characters and the token cannot be retrieved. If you lose it, create a new token.

Each token is valid for 18 months. The tokens table lists each token's **Name** and the user who created it, the **Token** (last four characters), its **Created** date, and its **Status** (**Active**, **Expired**, or **Revoked**) with its expiration or revocation date. Creating a new token keeps existing tokens valid, so you can create one token per gateway or environment and rotate tokens without downtime.

> [!NOTE]
>
> The ingest token authorizes trace uploads for your account. Treat it as a secret and supply it to Bifrost through your platform's secret management (for example, a Kubernetes secret mapped to an environment variable) rather than committing it to a config file in plaintext.

### Step 2: Configure OpenTelemetry on Bifrost

Under **Step 2: Configure OpenTelemetry on Bifrost**, Vantage shows the plugin configuration to use. Select the copy icon to copy it:

```json theme={null}
{
  "collector_url": "https://ingest.vantage.sh/v1/traces",
  "protocol": "http",
  "trace_type": "genai_extension",
  "trace_headers": {
    "Authorization": "env.VANTAGE_INGEST_AUTHORIZATION"
  },
  "disable_content_logging": true,
  "plugin_span_filter": {
    "mode": "include",
    "plugins": []
  }
}
```

| Field | Value | Purpose |
| - | - | - |
| `collector_url` | `https://ingest.vantage.sh/v1/traces` | The Vantage ingest endpoint. Bifrost posts to this URL exactly as written, so include the `/v1/traces` path. |
| `protocol` | `http` | Sends traces as OTLP over HTTPS. |
| `trace_type` | `genai_extension` | Bifrost's GenAI semantic-convention trace format, which carries the provider, model, and token usage Vantage reads. |
| `trace_headers.Authorization` | `env.VANTAGE_INGEST_AUTHORIZATION` | Reads the `Authorization` header value from an environment variable at runtime, so the token is never stored in your Bifrost configuration. |
| `disable_content_logging` | `true` | Stops Bifrost from exporting prompt and completion content. Vantage does not need it. |
| `plugin_span_filter` | `{"mode": "include", "plugins": []}` | Drops the spans Bifrost's own plugins emit and keeps the request and LLM call spans that carry usage. |

**1. Set the ingest token environment variable**

On every Bifrost instance, set `VANTAGE_INGEST_AUTHORIZATION` to the **complete** header value: the word `Bearer`, a space, and the token from [Step 1](#step-1-create-the-feed-and-an-ingest-token). Bifrost replaces the whole header value with the variable, so omitting `Bearer ` causes Vantage to reject the traces.

```bash theme={null}
export VANTAGE_INGEST_AUTHORIZATION="Bearer vntg_ti_<your-token>"
```

**2. (AWS Bedrock only) Declare the AWS account**

On each Bifrost deployment that calls Bedrock, add `cloud.account.id` to the `OTEL_RESOURCE_ATTRIBUTES` environment variable. Replace `123456789012` with the 12-digit ID of the AWS account that owns the credentials Bifrost uses to call Bedrock:

```bash theme={null}
export OTEL_RESOURCE_ATTRIBUTES="cloud.account.id=123456789012"
```

If `OTEL_RESOURCE_ATTRIBUTES` is already set, append the attribute to the existing comma-separated list instead of replacing it, so you keep your other attributes:

```bash theme={null}
export OTEL_RESOURCE_ATTRIBUTES="service.name=bifrost,deployment.environment=production,cloud.account.id=123456789012"
```

On Kubernetes, set the variable under the Bifrost container's `env` in your Deployment manifest:

```yaml deployment.yaml theme={null}
spec:
  template:
    spec:
      containers:
        - name: bifrost
          # Keep the container's existing configuration and environment variables.
          env:
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "service.name=bifrost,deployment.environment=production,cloud.account.id=123456789012"
```

If the variable already exists, the change is appending the account attribute to its value:

```yaml deployment.yaml theme={null}
- name: OTEL_RESOURCE_ATTRIBUTES
  value: "service.name=bifrost,deployment.environment=production" # [!code --]
  value: "service.name=bifrost,deployment.environment=production,cloud.account.id=123456789012" # [!code ++]
```

`OTEL_RESOURCE_ATTRIBUTES` is an environment variable on the Bifrost process, not a field in the `otel` plugin's `config.json`. Skip this step for deployments that don't call Bedrock. See [AWS Bedrock Usage Through Bifrost](#aws-bedrock-usage-through-bifrost) for what the value declares and how to choose it.

**3. Enable the OpenTelemetry plugin**

Add the configuration to Bifrost's OpenTelemetry plugin using whichever method you manage Bifrost with:

* **Web UI:** Go to **Observability** > **OpenTelemetry** and enter the values from the table above, including **Collector URL**, **Trace Type**, **Protocol**, and **Headers**. Use **Configure Plugin Tracing** to exclude plugin spans.
* **`config.json`:** Add the configuration as the `config` of the `otel` plugin:

```json config.json theme={null}
{
  "plugins": [
    {
      "enabled": true,
      "name": "otel",
      "config": {
        "collector_url": "https://ingest.vantage.sh/v1/traces",
        "protocol": "http",
        "trace_type": "genai_extension",
        "trace_headers": {
          "Authorization": "env.VANTAGE_INGEST_AUTHORIZATION"
        },
        "disable_content_logging": true,
        "plugin_span_filter": {
          "mode": "include",
          "plugins": []
        }
      }
    }
  ]
}
```

* **Helm:** Set the same keys under `bifrost.plugins.otel.config` in your values file, and map `VANTAGE_INGEST_AUTHORIZATION` from a Kubernetes secret.

If you already export Bifrost traces to another OpenTelemetry backend, add Vantage as an additional profile rather than replacing your existing one. See the [Bifrost OpenTelemetry documentation](https://docs.getbifrost.ai/features/observability/otel) for multi-profile configuration and the full field reference.

> [!NOTE]
>
> `trace_headers` requires Bifrost v2.0.0 or later. On v1.5.9 to v1.x, use `headers` instead, with the same `Authorization` value.
>
> Starting with Bifrost v2.3.0, the web UI and API reject `env.` references in the OpenTelemetry plugin when Bifrost's dashboard authentication is turned off. In that case, turn on dashboard authentication or configure the plugin through `config.json` or Helm.

**4. Restart Bifrost**

Restart or redeploy Bifrost so it picks up the new environment variables, along with any `config.json` or Helm changes. On Kubernetes, applying the updated Deployment manifest rolls out new pods with the new environment. Traces begin flowing to Vantage with your next requests through the gateway.

### Step 3: Configure Cost Integrations

Under **Step 3: Configure Cost Integrations**, select **Configure Providers**. On the **Configure Bifrost Providers** screen, under **Provider Connections**, select the connected cost integrations that should receive enrichment from Bifrost, then select **Save**.

> [!WARNING]
>
> Select **one cost integration per provider**, except AWS. Bifrost usage for other providers doesn't identify the provider account, so Vantage can't tell apart multiple integrations for the same provider. To switch to a different integration for a provider, deselect the current one first.
>
> * **AWS:** Select every AWS cost integration that contains accounts whose Bedrock usage you want to enrich. Each integration can include multiple member accounts, and Vantage uses the account each Bifrost deployment declares to tell them apart. See [AWS Bedrock Usage Through Bifrost](#aws-bedrock-usage-through-bifrost).
> * **Anthropic:** The **Claude API** and **Claude.ai** integrations count as the same provider, so choose the one whose bill your Bifrost traffic lands on: **Claude.ai** for Claude Code subscription usage, or **Claude API** for usage served with your organization's API keys.

Route all traffic for each provider you select through Bifrost, so that every request billed to the integration carries Bifrost's tags. Vantage enriches costs for the selected integrations on each provider's next data refresh. Provider cost integrations you connect later are not enriched automatically; return to **Configure Providers** to enable them.

### Step 4: Configure Key Mappings

Under **Step 4: Configure Key Mappings**, map each Bifrost provider key to the OpenAI or Anthropic (Claude API) API key it uses, so Vantage tags that key's usage only on that API key's cost rows. A Bifrost key ID is the ID Bifrost assigns to a provider key you configured in Bifrost, not a virtual key. Key mappings are optional; unmapped usage is matched by day, model, and token type.

Configure an OpenAI or Anthropic cost integration in [Step 3](#step-3-configure-cost-integrations) before you add key mappings. The provider keys you can choose come from the integrations selected there.

Once traffic flows, Bifrost keys that Vantage sees in your traces appear in the table automatically with an **Unmapped** status, and a warning shows how many keys are unmapped. The table lists each key's **Bifrost key ID**, **Provider**, **Provider key**, and **Status** (**Mapped** or **Unmapped**).

**1. Open the mapping dialog**

For a key Vantage has already seen, select **Map key** in its row. To map a key before traffic arrives, select **Add Key Mapping** and enter its **Bifrost key ID**. You can't change the ID of a key Vantage has seen in your traffic.

**2. Choose the provider key**

Select the **Provider**, then the **Provider key** that this Bifrost key uses. Only key IDs and names are shown, never secrets.

**3. Save the mapping**

Select **Save mapping**.

To change a mapping, select **Edit** in its row. To remove one, select the delete icon in its row, then select **Remove mapping** in the **Remove key mapping?** dialog.

Key mapping changes apply to the current month's Bifrost usage at the provider's next data refresh. Earlier months change only when they are re-imported, and then use the latest mappings.

> [!TIP]
>
> To confirm setup worked, send a few requests through Bifrost, then wait for the next data refresh of a selected provider. The feed's **Status** on the **Bifrost** page changes from **Pending** to **Importing** and then **Stable**, and the feed's **Enrichment History** tab shows an enrichment run for each selected integration. If you are not sure which costs were enriched, see [Troubleshooting](#troubleshooting).

## Attribute Usage with Virtual Keys and Request Dimensions

Bifrost Enrichment tags each enriched row with the attribution your gateway already knows about, plus any custom dimensions you attach per request.

### Virtual Keys

Issue a Bifrost [virtual key](https://docs.getbifrost.ai/features/governance/virtual-keys) for each team, application, or customer you want to attribute spend to, and name it accordingly (for example, `search-team` or `support-bot`). Vantage tags each request's usage with the virtual key's name as `vntg:ai:virtual_key`. Applications send the virtual key in the `x-bf-vk` header or as `Authorization: Bearer sk-bf-...`.

Usage without a virtual key carries no `vntg:ai:virtual_key` tag. New deployments of Bifrost v2.2.6 and later require a virtual key on every request by default. On older versions, and on existing deployments that haven't turned it on, turn on **Enforce Virtual Keys on Inference** in Bifrost's security settings (`client.enforce_auth_on_inference` in `config.json`) to attribute all gateway traffic.

### Custom Dimensions

Attach your own dimensions with `x-bf-dim-<name>` request headers. No additional Bifrost configuration is needed. Each dimension becomes a tag on the enriched rows for that request's usage. The tag key is the header name with the `x-bf-dim-` prefix removed, lowercased, with hyphens kept, so `x-bf-dim-Cost-Center` becomes the tag `cost-center`. Bifrost reserves the names `path` and `method`, so `x-bf-dim-path` and `x-bf-dim-method` are ignored.

```bash theme={null}
curl https://<your-bifrost-host>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-vk: sk-bf-<your-virtual-key>" \
  -H "x-bf-dim-team: search" \
  -H "x-bf-dim-feature: summarization" \
  -H "x-bf-dim-environment: production" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'
```

This request's usage is tagged `team=search`, `feature=summarization`, and `environment=production`, along with the virtual key's name.

Follow these guidelines for dimensions:

* **Keep casing consistent:** Vantage stores tag values exactly as sent, so `Search` and `search` become two different values. Standardize values in your applications, or merge variants afterward with a [Virtual Tag](https://docs.vantage.sh/tagging.md).
* **Use bounded values:** Dimensions like team, feature, and environment work well. Avoid per-request identifiers such as request IDs or timestamps: Vantage drops tag keys whose values are nearly unique per request.
* **Do not send secrets or personal data:** Dimension values become visible tags in Vantage.

## Manage Bifrost Enrichment Sources

Manage your feed from the [**Bifrost** integration page](https://console.vantage.sh/settings/bifrost_enrichment_sources). Each account has one Bifrost feed. The **Connected Feeds** table lists it with its **Feed Token**, **Cost Providers**, **Status** (for example, **Pending** before an import starts, **Importing** while one runs, **Stable** once all imports succeed, **Warning** if only some imports fail, **Error** if an import fails, or **Paused** if enrichment is paused), and **Created On** date.

Select the feed token to open the feed. It has two tabs: **Enrichment History** and **Manage**, which holds the **Uses** section, the setup steps, ingest tokens, provider selection, and key mappings.

### Choose Which Integrations Are Enriched

On the **Manage** tab, select **Configure Providers** to change which connected cost integrations receive enrichment. You can enrich one cost integration per provider, or several AWS integrations. Disabling an integration stops going-forward enrichment for it but leaves its existing enriched history in place.

### Manage Ingest Tokens

Create additional tokens under **Step 1: Manage Ingest Tokens** on the **Manage** tab, for example to give each gateway or environment its own token, or to rotate a token before it expires. To rotate a token, create a replacement, update `VANTAGE_INGEST_AUTHORIZATION` on your Bifrost instances and restart them, then select **Revoke** next to the old token and confirm with **Revoke token** in the **Revoke ingest token?** dialog. Requests that use a revoked token are rejected within about 30 seconds, and other tokens keep working. Revoking cannot be undone.

You can also list, create, and revoke ingest tokens with the Vantage API. See [List ingest tokens](https://docs.vantage.sh/api/ingesttokens/list-ingest-tokens.md), [Create ingest token](https://docs.vantage.sh/api/ingesttokens/create-ingest-token.md), and [Revoke ingest token](https://docs.vantage.sh/api/ingesttokens/revoke-ingest-token.md).

### View Enrichment History

Open the feed and select the **Enrichment History** tab. The **Enrichment Runs** table shows every run for this feed.

The **Enrichment Runs** table lists one row per provider cost integration and billing period that ran enrichment, newest first, with columns for the **Integration** (and its account), **Status**, **Tokens Kept**, **Log Lines Kept**, **Bill Match**, **Billing Period**, and **Last Run At**. Lifecycle changes appear as their own rows: **Added** when enrichment is first enabled for an integration, and **Paused** or **Resumed** when you stop, disable, resume, or re-enable it.

The three percentages look similar but measure different things at different stages, so a low number in one column means something very different from a low number in another:

| Metric | Stage | Counts | A Low Value Means |
| - | - | - | - |
| **Tokens Kept** | Join | Tokens | Your logs were read fine, but the usage in them did not line up with your provider bill. |
| **Log Lines Kept** | Log Scan | Log lines | Vantage could not read or index many of your log lines, usually because records are malformed or missing required fields. |
| **Bill Match** | Join | Provider cost rows | Many provider cost rows received no logged usage at all, so they passed through unsplit. Often your logs cover only part of your traffic. |

A low percentage does not change your totals. Usage Vantage cannot attribute stays on a **leftover** row, the unallocated remainder of the original cost row, so the enriched rows always add back up to what the provider billed.

Select the **Tokens Kept** percentage on any run to open **Token Metrics**, which breaks that run down by disposition across the two stages and lets you view sample records for anything that did not make it through.

> [card] [LLM Enrichment History](https://docs.vantage.sh/llm_enrichment_import_history.md)
>
> Full reference for the Enrichment History screen: every column and status, how to read the three percentages, the Log Scan and Join dispositions with a fix for each, sample record fields, and a troubleshooting table.

### Pause or Resume Enrichment

To pause enrichment, open the feed's **Manage** tab and, under **Uses**, select **Pause** next to **Enrichment**. Vantage stops enriching new cost data for the feed, but your existing enriched history is left unchanged and the feed's ingest tokens keep working. While enrichment is paused, you can't change the feed's providers or key mappings.

To resume, select **Resume** next to **Enrichment**. Resuming restarts going-forward enrichment for the integrations that were active when you paused it; integrations you had already disabled individually stay disabled.

> [!NOTE]
>
> Pausing enrichment does not re-import or roll back already-enriched costs. It also does not stop Bifrost from exporting traces. To stop sending usage, disable the Vantage OpenTelemetry profile in Bifrost, and revoke its ingest tokens if you no longer need them.

## View Enriched Costs on Cost Reports

Once enrichment runs, a single provider cost line is split into multiple rows, each carrying enrichment tags. You can filter and group by these tags anywhere tags are supported: [Cost Reports](https://docs.vantage.sh/cost_reports.md), [Virtual Tags](https://docs.vantage.sh/tagging.md), [Budgets](https://docs.vantage.sh/budgets.md), and [Cost Alerts](https://docs.vantage.sh/cost_alerts.md).

Because enrichment splits (allocates) your provider costs, enrichment tags behave like Vantage's [cost allocation tags](https://docs.vantage.sh/tagging.md#cost-allocation-tags): you can build a Virtual Tag on them, but a cost can be allocated only once, so an enrichment tag can belong to only [one allocation chain](https://docs.vantage.sh/tagging.md#virtual-tag-allocation-rules).

### Enrichment Tag Reference

Vantage builds each usage record's tags from the Bifrost trace: your `x-bf-dim-*` dimensions and the virtual key name.

| Tag key | Description | Example value |
| - | - | - |
| *Your dimension names* | Each `x-bf-dim-<name>` header becomes a tag keyed by `<name>`, lowercased, on the enriched rows for that request's usage. | `team=search` |
| `vntg:ai:virtual_key` | The name of the Bifrost virtual key the request used. | `vntg:ai:virtual_key=support-bot` |
| `vntg:ai:model` | The normalized model identifier that generated the cost, derived from the cost row. Vantage adds it to every enriched row. | `vntg:ai:model=gpt-4o-mini-2024-07-18` |
| `vntg:ai:model_provider` | The provider family inferred from the model (for example, OpenAI, Anthropic, Google), added automatically alongside `vntg:ai:model` when the family is recognized. | `vntg:ai:model_provider=OpenAI` |
| `vntg:ai:token_type` | The token kind the enriched row covers: `input`, `output`, `cache_read`, or `cache_write`. Added automatically to every enriched row. | `vntg:ai:token_type=input` |
| *Provider's existing tags* | Any tags Vantage already puts on the provider's cost rows are preserved on the enriched rows, including [Managed AI Tags](https://docs.vantage.sh/managed_ai_tags.md) such as `vntg:ai:user_email` on Claude.ai Claude Code rows. If a non-managed provider tag shares a key with a usage tag, the enrichment value wins. | — |

Your dimension names appear as tags without a provider prefix, so a key like `team` lines up across OpenAI, Anthropic, and the other providers, and you can group your entire AI stack by one `team` tag. Because Bifrost lowercases header names, `x-bf-dim-Team` and `x-bf-dim-team` produce the same `team` key, but values keep their casing. Dimension names that collide with a Vantage-managed name (such as `model` or `user_id`) are re-emitted under the `vntg:ai:` prefix, and keys that already start with `vntg:ai:` are ignored.

> [!NOTE]
>
> Enriched rows retain the provider's existing tags and add the Vantage-managed `vntg:ai:*` tags (such as `vntg:ai:model`); split rows also carry the tags from their usage slice. The leftover row (usage not covered by Bifrost traces) keeps the provider's existing tags and the applicable `vntg:ai:*` tags but carries none of the slice tags. Request identifiers are never turned into tags. Vantage may also apply a tag denylist to drop noisy or sensitive keys before they become tags.

Enrichment tags behave like any other provider tag in the console:

* **To group:** open the **Group By** menu, select **Tag**, and choose the tag key, for example `vntg:ai:model`, or one of your own keys such as `team`.
* **To filter:** open the **Filters** menu, click **New Rule**, select **Tag**, choose the **Tag Key**, then pick an operator and one or more values.

The tag keys appear in the **Tag Key** dropdown once enriched costs exist. If you use a handful of keys often, mark them as [preferred tags](https://docs.vantage.sh/tagging.md#preferred-tags) so they sort to the top of these menus.

## Troubleshooting

> [accordion] My feed stays on Pending
>
> **Pending** means Vantage has not run an enrichment import for this source yet. Enrichment runs during each provider's regular cost ingestion, so a newly connected source shows **Pending** until the next data refresh of a provider it enriches. See the [provider data refresh documentation](https://docs.vantage.sh/provider_data_refresh.md) for per-provider timing. If the status is still **Pending** after that refresh, check the following:
>
> * **Enrichment** is turned on under **Uses** on the feed's **Manage** tab. A new feed starts with enrichment turned off and shows **Paused** until you turn it on.
> * Bifrost is exporting traces: the OpenTelemetry plugin is enabled with the configuration from [Step 2](#step-2-configure-opentelemetry-on-bifrost), Bifrost was restarted after you set the environment variable, and requests are flowing through the gateway.
> * `VANTAGE_INGEST_AUTHORIZATION` is set on every Bifrost instance to `Bearer ` followed by the full token, and the token is **Active** (not **Expired** or **Revoked**) under **Step 1: Manage Ingest Tokens**.
> * Bifrost can reach `https://ingest.vantage.sh` over outbound HTTPS. Check Bifrost's logs for export errors such as `401` or `403` responses, which mean the token is missing, malformed, expired, or revoked.
> * At least one cost integration is selected under **Configure Providers** ([Step 3](#step-3-configure-cost-integrations)), with no more than one per provider other than AWS.

> [accordion] Enrichment History shows No logs
>
> Vantage received no usable Bifrost usage for that provider and billing period, so there was nothing to enrich. This is expected for periods before you started exporting traces. For recent periods, confirm Bifrost is still exporting (see the **Pending** entry above), and that the traffic for that provider actually goes through Bifrost. See [Import History status values](https://docs.vantage.sh/llm_enrichment_import_history.md#status-values).

> [accordion] A provider is not being enriched
>
> * Confirm the provider has exactly one cost integration selected under **Configure Providers** (AWS can have several). If you see `Select no more than one cost integration per provider.` when saving, deselect the extra integration.
> * Confirm the provider is one of the supported providers and that its cost integration is active. OpenRouter, Fireworks, and Azure CSP aren't supported through Bifrost.
> * For Anthropic, confirm you selected the integration whose bill your Bifrost traffic lands on: **Claude.ai** for Claude Code subscription usage, or **Claude API** for usage served with your API keys.
> * Allow a full data refresh for that provider to complete after connecting. Enrichment applies on the next refresh.

> [accordion] Bedrock usage isn't attributed to the right AWS account
>
> * Confirm each Bifrost deployment that calls Bedrock has `cloud.account.id=<12-digit account ID>` in its `OTEL_RESOURCE_ATTRIBUTES` environment variable, that the value is the account that signs its Bedrock requests, and that you restarted Bifrost after setting it. See [AWS Bedrock Usage Through Bifrost](#aws-bedrock-usage-through-bifrost).
> * Confirm the AWS cost integration that contains that account is selected under **Configure Providers**.
> * On the feed's **Enrichment History** tab, open the AWS run's [Token Metrics](https://docs.vantage.sh/llm_enrichment_import_history.md#join-dispositions). **Account scope empty** means usage declared an account that has no matching Bedrock cost rows. Open its [sample records](https://docs.vantage.sh/llm_enrichment_import_history.md#view-sample-records): `failed_on_log_values` lists the account IDs your deployments declared, which you can compare to the accounts on your bill. **Ambiguous sibling withheld** means usage without a declared account was withheld because more than one AWS integration is selected.
> * On a [Cost Report](https://docs.vantage.sh/cost_reports.md) filtered to Amazon Bedrock, group by account and by `vntg:ai:virtual_key` or one of your dimension tags to confirm each deployment's enriched costs land on the expected account.

> [accordion] Some of a key's spend has no Bifrost tags
>
> Tags from Bifrost apply only to usage that went through Bifrost. If you also call your provider directly with the same API key, that usage stays on the bill under the key without Bifrost's tags. To tag all of a key's spend, send all of its traffic through Bifrost, or use a separate key for traffic outside Bifrost.

> [accordion] Claude Code usage isn't attributed to individual users
>
> Confirm that you run Bifrost Enterprise, that each user exists in Bifrost with the same email as their Claude seat, and that each user's Claude Code requests send their own virtual key in the `x-bf-vk` header. Also confirm the **Claude.ai** integration, not **Claude API**, is selected under **Configure Providers**. Users whose email doesn't match a Claude Code cost row appear under [**User email scope empty**](https://docs.vantage.sh/llm_enrichment_import_history.md#join-dispositions) in the run's Token Metrics, and its sample records list the emails that didn't match. See [Claude Code Usage Through Bifrost](#claude-code-usage-through-bifrost).

> [accordion] My costs are not being split
>
> Enrichment can only split costs by dimensions present in your usage. Costs pass through without allocation splits when any of the following is true:
>
> * Enrichment is paused, or no usage was received for that billing period.
> * The cost row's model or token type could not be matched to Bifrost usage for that provider, date, and token kind.
> * The requests carried no virtual key or dimensions, so there was nothing to split by. Issue [virtual keys](#virtual-keys) or attach [custom dimensions](#custom-dimensions).

> [accordion] Custom tags from x-bf-dim-\* headers are missing
>
> * Confirm your application sends the `x-bf-dim-<name>` headers on its requests to Bifrost.
> * Look for the tag under the lowercased name with the prefix removed. For example, `x-bf-dim-Cost-Center` appears as `cost-center`.
> * Don't use `path` or `method` as dimension names. Bifrost reserves them and ignores `x-bf-dim-path` and `x-bf-dim-method`.
> * Use values that repeat across requests. Vantage drops tag keys whose values are nearly unique per request.
> * Allow the next data refresh for the provider to complete. If the tags still don't appear, contact [Vantage Support](mailto:support@vantage.sh).

> [accordion] I can't update providers or key mappings
>
> If you see `This Bifrost source is stopped. Resume it before updating providers.` or `This Bifrost source is stopped. Resume it before updating key mappings.`, enrichment is paused or hasn't been turned on yet. Under **Uses** on the **Manage** tab, select **Resume** next to **Enrichment**, or for a new feed, select **Enrichment** and then **Save Uses**. See [Pause or Resume Enrichment](#pause-or-resume-enrichment).
>
> If **Add Key Mapping** is unavailable and you see `Configure a cost integration in Step 3 before adding key mappings.`, select an OpenAI or Anthropic (Claude API) cost integration under **Configure Providers** first.

> [accordion] I lost my ingest token
>
> Tokens are shown only once and cannot be retrieved later. Create a new token under **Step 1: Manage Ingest Tokens**, update `VANTAGE_INGEST_AUTHORIZATION` on your Bifrost instances, and restart them. Then revoke the old token. If copying fails in your browser, select **Show** and copy the token manually before you leave the page.

> [accordion] I can't tell which costs were enriched
>
> Enrichment tags appear in the console as regular provider tags. To confirm what was enriched:
>
> * **Check coverage in Enrichment History:** Open the source's [Enrichment History](https://docs.vantage.sh/llm_enrichment_import_history.md) and review **Tokens Kept** (the share of your logged tokens Vantage attached to a cost row) and **Bill Match** (the share of eligible provider cost rows that received logged usage) for each integration and billing period.
> * **Check a Cost Report:** Filter to the provider, then group by one of your own tag keys. Costs from requests that carried that key show its values. The leftover row (the portion of the bill your usage did not cover) and any usage sent without that key appear as **Not tagged with** the key name.

> [accordion] My totals changed after enabling enrichment
>
> Totals should not change. Splits are additive and always sum to the original cost row to the cent, even when multiple sources are connected. If a total appears different, this is not expected behavior; contact [Vantage Support](mailto:support@vantage.sh).

## Use Cases

Each row below shows example attribution to set up in Bifrost and what it enables in Vantage. The dimension names are examples; you choose your own. All rows assume Bifrost is exporting traces to Vantage.

| Use Case | Set up in Bifrost | What It Enables |
| - | - | - |
| Chargeback by team | A virtual key per team, or an `x-bf-dim-team` header | Group a [Cost Report](https://docs.vantage.sh/cost_reports.md) by `vntg:ai:virtual_key` or `team` for per-team LLM chargeback, or roll values into a business hierarchy with a [Virtual Tag](https://docs.vantage.sh/tagging.md). |
| Per-application spend on shared keys | A virtual key per application | Attribute spend to each application even when they all share one provider API key, which the provider bill cannot break apart. |
| Claude Code spend by developer and team | Bifrost Enterprise users with emails that match their Claude seats, and each user's Claude Code routed through Bifrost's `/anthropic` route with their own virtual key | Each developer's Claude.ai Claude Code costs carry the virtual key and dimensions from that developer's requests, so you can group them by team or project alongside `vntg:ai:user_email`. |
| Bedrock spend by team across AWS accounts | `cloud.account.id` on each deployment that calls Bedrock, plus virtual keys or `x-bf-dim-*` headers | Attribute each AWS account's Bedrock costs to the teams and applications that drove them, even when several deployments share an account. |
| Per-feature or per-workflow spend | `x-bf-dim-feature` or `x-bf-dim-workflow` headers | Compare cost per product feature or workflow (for example, `summarization` vs. `classification`). |
| Environment separation | An `x-bf-dim-environment` header | Filter non-production inference out of showback reports, or budget each environment (`production`, `staging`) separately. |

## Frequently Asked Questions

> [accordion] Which providers are supported?
>
> OpenAI, Anthropic (Claude API or Claude.ai), AWS Bedrock, Google Cloud (Vertex AI Gemini and Marketplace Claude), Azure, SpaceXAI, Baseten, Modal, and Together AI. Vantage routes each usage record to the matching provider's costs based on the provider Bifrost called. You need an active Vantage cost integration for each provider whose costs you want to enrich. Azure support covers direct Azure billing; Azure CSP billing accounts are not supported. OpenRouter and Fireworks aren't supported through Bifrost.

> [accordion] Is AWS Bedrock supported?
>
> Yes. Bedrock usage through Bifrost enriches the Amazon Bedrock costs from your AWS cost integration. Declare the AWS account that signs each deployment's Bedrock requests with the `cloud.account.id` resource attribute so Vantage can match usage to the right account. See [AWS Bedrock Usage Through Bifrost](#aws-bedrock-usage-through-bifrost).

> [accordion] Do I need to map my Bifrost provider keys to my provider API keys?
>
> It's recommended for exact attribution, but not required. With a key mapping, a Bifrost key's usage is tagged only on that API key's cost rows. Unmapped usage is matched by day, model, and token type. Key mappings are available for OpenAI and Anthropic (Claude API) keys, and you manage them in [Step 4](#step-4-configure-key-mappings) on the feed's **Manage** tab.

> [accordion] How does Claude Code attribution work?
>
> When developers sign in to Claude Code with their Anthropic account and route it through Bifrost Enterprise, Bifrost records each user's email. On a Claude.ai cost integration, Vantage matches that usage to the same user's Claude Code cost rows, so the Bifrost tags land on that user's costs. Those rows keep the `vntg:ai:user_email` tag from the Claude.ai bill. Each user needs to exist in Bifrost with the same email as their Claude seat and send their own virtual key. See [Claude Code Usage Through Bifrost](#claude-code-usage-through-bifrost).

> [accordion] Do I need to change my application code?
>
> No. You enable Bifrost's OpenTelemetry plugin, and your applications keep calling Bifrost as they do today. To attribute costs by your own dimensions, issue virtual keys or add `x-bf-dim-*` headers to requests. Vantage can't infer ownership from token counts alone.

> [accordion] Can I run multiple Bifrost instances or replicas?
>
> Yes. Every Bifrost instance or replica can export to the same feed with the same ingest token. You can also create a separate token for each gateway or environment; all tokens feed the same Bifrost feed for your account. If your deployments call Bedrock under different AWS accounts, set `cloud.account.id` on each one.

> [accordion] Do I still need Custom LLM Enrichment?
>
> Not for traffic that goes through Bifrost. Bifrost Enrichment reads usage straight from your gateway, so you don't need to transform it into the common schema yourself. [Custom LLM Enrichment](https://docs.vantage.sh/custom_llm_enrichment.md) remains the right choice for traffic that doesn't go through Bifrost and for teams that already emit the Token Cost Allocation Specification from their own collectors.

> [accordion] Should I also use Custom LLM Enrichment for the same traffic?
>
> No. If the same requests are reported by both Bifrost Enrichment and [Custom LLM Enrichment](https://docs.vantage.sh/custom_llm_enrichment.md), [AWS Bedrock LLM Enrichment](https://docs.vantage.sh/aws_bedrock_enrichment.md), or another gateway source, your cost isn't double counted, but each source's tags get only about half of the matching cost. Token Metrics shows the excess usage as **Bill demand short of log usage**. Send each request's usage through one enrichment source.

> [accordion] What Vantage permissions do I need to enable this?
>
> You need the **Organization Owner** or **Integration Owner** role to connect the source. Viewing the enriched costs does not require a special role; the resulting tags follow the same access rules as other cost data. See [Role-Based Access Control](https://docs.vantage.sh/rbac.md).

> [accordion] Will this change my totals or break existing reports?
>
> No. Splits are additive and always sum to the original cost row. Existing provider-level reports continue to show the same totals; enrichment only makes new dimensions available on the underlying rows.

> [accordion] Does Vantage store my prompt content?
>
> No. Enrichment uses the provider, model, token counts, and attribution fields on each trace. With `disable_content_logging` set to `true`, as in the recommended configuration, Bifrost does not export prompt or completion content to Vantage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.