> ## 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. # Custom LLM Enrichment > Attribute LLM spend to teams, users, applications, and features by delivering your own per-request token telemetry to an S3 bucket that Vantage reads and joins to your provider costs. Vantage reads your own per-request LLM usage logs from an S3 bucket and joins them to your model-provider costs. Each record describes one model call: the provider, model, token counts, and the allocation `tags` you attach. Vantage splits each matching cost row into enriched rows by token share and adds your `tags` to each row. This surfaces spend the provider bill never itemized, so you can filter and group it in [Cost Reports](/cost_reports), [Virtual Tags](/tagging), [Segments](/segments), [Budgets](/budgets), and [Cost Alerts](/cost_alerts). Because you emit the telemetry yourself, this works with or without an AI gateway, even when applications share one API key the bill cannot break apart. The **Custom LLM Enrichment** integration enriches costs for Vantage's native model-provider integrations: **OpenAI**, **Anthropic**, **AWS Bedrock**, **Google Cloud** (Vertex AI Gemini and Marketplace Claude), and **Azure OpenAI**. You deliver one telemetry stream in the **Token Cost Allocation Specification**, a single, provider-agnostic schema, and Vantage routes each record to the matching provider's costs. Enrichment is metadata-only. Vantage reads the provider, model, token counts, and the allocation `tags` you choose to emit. Vantage does not collect or store your prompt or completion content, and it is never written to a Vantage-owned artifact. This data is not used to train any models. ## How It Works Your application (or the gateway in front of it) emits one JSON record per LLM request in the [Token Cost Allocation Specification](#step-1-emit-telemetry-in-the-common-schema). You write those records to an S3 bucket you own, and Vantage joins them to your provider costs during that provider's cost ingestion. The enrichment pipeline runs through the following steps: | Stage | What Happens | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1. Emit | Your application or gateway writes one common-schema JSON record per LLM request, including the allocation `tags` you want to attribute cost by. | | 2. Deliver | You write those records as gzipped JSONL to an S3 bucket you own, partitioned by UTC date. | | 3. Read | Vantage reads the log objects from S3 using a cross-account IAM role you grant read access to. | | 4. Index | Vantage deduplicates records on `event_id` within each day (when duplicates exist, the record with the highest total token count wins) and aggregates tokens into a per-provider usage index keyed by date, provider, model, and token kind. | | 5. Join and split | During each provider's cost ingestion, Vantage joins each cost row to the usage index and splits it proportionally by token share. | | 6. Tag | Each enriched row is written with the `tags` from its usage slice plus a `model` tag. | | 7. Analyze | The enriched, tagged costs become available in Cost Reports, Virtual Tags, Segments, Budgets, and Alerts. | ### How Cost Rows Are Split For each matched cost row, the cost is allocated proportionally across the tag slices present in your telemetry, weighted by token usage: $$ \text{attributed cost} = \text{cost row} \times \frac{\text{slice tokens}}{\text{total matched tokens for row}} $$ Splits are additive: the sum of the enriched rows always equals the original cost row to the cent. Existing provider-level reports continue to show the same totals; enrichment only *makes new dimensions available* on the underlying rows. Consider the below example: one cost row for `gpt-5.2-2025-12-11` is `$100` for the day, covering 100M input tokens. Your telemetry for that day groups into these tag slices: | Tag slice | Input tokens | `tags` | | -------------------------------- | ------------ | ------------------------------------ | | Slice A | 50M | `team=growth, purpose=summarization` | | Slice B | 30M | `team=research, purpose=eval` | | (usage not covered by telemetry) | 20M | (none) | After enrichment, the single `$100` row becomes three rows: | Amount | `team` | `purpose` | Source | | ------ | -------- | ------------- | -------------- | | `$50` | growth | summarization | Enriched split | | `$30` | research | eval | Enriched split | | `$20` | — | — | Leftover | The total is unchanged at `$100`. The **leftover** row carries the portion of the cost row's tokens that your telemetry does not cover; it keeps the provider's existing tags and the `model` tag but none of the slice `tags`, so totals always reconcile and no dollars are lost. Cost rows with no matching telemetry pass through without allocation splits. If your telemetry instead reports more usage than the provider billed, Vantage still allocates only the billed cost, split across your tag slices in proportion to each slice's usage. The surplus telemetry does not create additional cost, and there is no leftover row in that case. ### 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 logs are picked up. See the [provider data refresh documentation](/provider_data_refresh) for per-provider timing. A billing period is enriched whenever it is processed while an active source exists, for as long as the matching logs remain in your bucket. Late-arriving logs for recent days are picked up automatically within the rolling three-day window. For older periods, Vantage re-enriches a day when the set of log objects for that day changes (files are added or removed) or when a full rebuild is triggered; replacing the contents of an existing object under the same key does not, on its own, re-trigger enrichment. Re-enrichment reads the already-normalized cost data, so it does not require a full cost re-import. ## Prerequisites Before you begin, make sure: * An active cost integration exists for at least one supported provider: [OpenAI](/connecting_open_ai), [Anthropic](/connecting_anthropic), [AWS](/connecting_aws), [Google Cloud](/connecting_gcp), or [Azure](/connecting_azure). * An active [AWS integration](/connecting_aws) (cross-account IAM role) exists for the account that owns the telemetry bucket. Vantage reads the bucket through this role, so it is required even when the costs you enrich come only from OpenAI, Anthropic, Google Cloud, or Azure. * You have an S3 bucket you own where you write (or will write) your telemetry. * You have a Vantage **Organization Owner** or **Integration Owner** role. See [Role-Based Access Control](/rbac). ## Set Up Custom LLM Enrichment Setup has two steps: [emit your telemetry in the common schema to S3](#step-1-emit-telemetry-in-the-common-schema) and [connect the source in Vantage](#step-2-connect-the-source-in-vantage), where you grant Vantage read access to the bucket and then review which providers Vantage detected. If you don't already produce these logs, the cold-start demo below turns an OpenAI or Anthropic API key into spec-conformant `YYYY/MM/DD/*.jsonl.gz` records you can deliver to S3, a fast way to see enrichment work before you instrument production traffic. {(() => { const [isMobile, setIsMobile] = React.useState(false); React.useEffect(() => { if (typeof window === 'undefined') return; const check = () => setIsMobile(window.innerWidth <= 768); check(); window.addEventListener('resize', check); return () => window.removeEventListener('resize', check); }, []); const innerStyle = isMobile ? { display: 'grid', gridTemplateColumns: '1fr', gap: 0, alignItems: 'stretch' } : { display: 'grid', gridTemplateColumns: 'minmax(0,1.2fr) minmax(0,1fr)', gap: 0, alignItems: 'stretch' }; const imageStyle = isMobile ? { minHeight: '180px', background: '#f8f7fa', backgroundImage: 'url(/img/custom-llm-source-cold-start.png)', backgroundSize: 'contain', backgroundRepeat: 'no-repeat', backgroundPosition: 'center' } : { minHeight: '190px', background: '#f8f7fa', backgroundImage: 'url(/img/custom-llm-source-cold-start.png)', backgroundSize: 'contain', backgroundRepeat: 'no-repeat', backgroundPosition: 'center' }; const contentStyle = isMobile ? { padding: '24px', display: 'flex', flexDirection: 'column', justifyContent: 'center' } : { padding: '28px 32px', display: 'flex', flexDirection: 'column', justifyContent: 'center' }; return ( { e.currentTarget.style.boxShadow = '0 8px 32px rgba(103, 66, 214, 0.15)'; e.currentTarget.style.borderColor = 'rgba(103, 66, 214, 0.35)'; }} onMouseLeave={(e) => { e.currentTarget.style.boxShadow = '0 4px 24px rgba(0,0,0,0.06)'; e.currentTarget.style.borderColor = 'rgba(0,0,0,0.06)'; }} >

Try the Cold-Start Demo

Turn an OpenAI or Anthropic API key into spec-conformant records in minutes.

Open on GitHub ↗
); })()} ### Step 1: Emit Telemetry in the Common Schema Records follow the Token Cost Allocation Specification. Write one JSON object per request as newline-delimited JSON (JSONL), gzip-compressed, under a date-partitioned path: ```text theme={null} s3:////YYYY/MM/DD/*.jsonl.gz ``` * Use the request timestamp's UTC date for the `YYYY/MM/DD` partition. * Place the logs at the bucket root or under any prefix (subfolder); keep the `YYYY/MM/DD` date structure at the end of the path. * Write one record per line; do not wrap records in an outer JSON array. * Batch many records into larger gzipped files rather than writing one object per request. * Vantage reads these logs from the connected bucket when importing provider cost data; logs are not pushed directly to Vantage. A single record looks like this: ```json theme={null} { "event_id": "ail_3EG...", // stable per-request dedup key "timestamp": "2026-05-26T17:59:06.235207Z", // UTC, explicit Z "provider": "openai", // provider identity, separate from model "model": "gpt-5.2-2025-12-11", // model as reported by the provider "resource_account_id": "proj_abc123", // provider-native account (e.g. OpenAI project) "provider_region": "us-east-1", // provider region "service_tier": "default", // provider processing tier "is_batch": false, // batch request "endpoint": "default", // default or regional "api_key_id": "key_abc123", // OpenAI key id or Anthropic actor email, never the secret sk-... "usage": { // at least one positive token count required "input_tokens": 2129, "uncached_input_tokens": 1557, "output_tokens": 112, "cache_read_input_tokens": 572, "cache_write_input_tokens": 0 }, "tags": { // arbitrary allocation dimensions "team": "growth", "purpose": "summarization" } } ``` The sections below define each part of the record: [Core fields](#core-fields) are required on every record, [Usage fields](#usage-fields) carry the token counts (at least one must be a positive integer), [Optional fields](#optional-fields) add context and extra allocation dimensions, [Tagging guidance](#tagging-guidance) explains how `tags` and top-level metadata become cost dimensions, and [Record validity](#record-validity) covers what makes a record count. #### Core Fields These fields are required on every record. | Field | Type | Requirement | Description | | ----------- | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `event_id` | String | **Required** | Stable, unique identifier for the request. Vantage uses it to deduplicate records; it is not available as an allocation dimension. | | `timestamp` | String | **Required** | Request time as an ISO 8601 timestamp in UTC with an explicit `Z` suffix. Determines the billing day the record joins to. | | `provider` | String | **Required** | AI provider that handled the request. Kept separate from `model` so a provider's costs only match that provider's telemetry. *See the accepted values below.* | | `model` | String | **Required** | Model identifier as reported by the provider, keeping any provider-specific prefixes (for example, Bedrock's `anthropic.` or Vertex's `models/`). This is the default join key against your provider cost data. | | `usage` | Object | **Required** | Token counts for the request. At least one [usage field](#usage-fields) must be a positive integer. | Set `provider` to the identity that matches your cost integration. | Provider | Accepted `provider` values | | ------------ | --------------------------------------- | | OpenAI | `openai` | | Anthropic | `anthropic` | | AWS Bedrock | `aws`, `bedrock` | | Google Cloud | `gcp`, `gemini`, `google`, `vertex` | | Azure OpenAI | `azure`, `azure_openai`, `azure-openai` | Vantage normalizes model identifiers on both sides so gateway logs and provider billing join even when they differ. For example, OpenAI billing always uses dated model names (`gpt-5.2-2025-12-11`) while your logs may use dated or undated names (`gpt-5.2`); Vantage prefers the dated form and normalizes undated names to match. #### Usage Fields The `usage` object is required. At least one field below must be a positive integer; no single field is always required, so include the counts that describe the request. | Field | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `input_tokens` | Total input tokens, including cached tokens. Used to derive uncached input when `uncached_input_tokens` is absent. | | `uncached_input_tokens` | Explicit uncached input token count. Preferred when available. | | `output_tokens` | Tokens generated by the model. | | `cache_read_input_tokens` | Input tokens read from a cache. Missing values are treated as zero during uncached-input derivation. | | `cache_write_input_tokens` | Input tokens written to a cache. Missing values are treated as zero during uncached-input derivation. | When `uncached_input_tokens` is omitted or null, Vantage derives it as: ```text theme={null} max(0, input_tokens - cache_read_input_tokens - cache_write_input_tokens) ``` #### Optional Fields These fields are optional. Include the ones present on each request to improve matching and add allocation dimensions. `resource_account_id` is recommended when one bucket carries logs for multiple integrations of the same provider. If you connect more than one integration for the same provider (for example, two OpenAI accounts) and your telemetry does not include `resource_account_id`, Vantage cannot tell which integration each record belongs to, and those integrations' costs will not be enriched. | Field | Type | Requirement | Description | | --------------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | String | Optional | Request status. Omit or leave it blank for successful requests, or set it to `success` (case-insensitive). Records with any other status are skipped. | | `resource_account_id` | String | Recommended | Provider account that generated the usage (OpenAI project or organization, Anthropic workspace or organization, AWS usage account, Azure subscription, or Google Cloud project). Include it when one bucket supplies logs for multiple integrations from the same provider so Vantage matches each request to the correct costs. Must be top-level; `tags.resource_account_id` is ignored. | | `service_tier` | String | Optional | Provider processing tier, used to match and allocate costs where applicable. Valid values depend on the provider. | | `is_batch` | Boolean | Optional | Whether the request used batch processing. Can affect provider-specific matching. | | `endpoint` | String | Optional | Endpoint class used for the request. Use `default` or `regional`. For OpenAI, enables matching regional-endpoint cost line items when present. A top-level value overrides `tags.endpoint`. | | `api_key_id` | String | Optional | Provider-native API key identifier. For OpenAI, the `key_...` id from the usage or admin API (never the secret `sk-...` key); for Anthropic Analytics, the actor email associated with the request. Must be top-level. Supports grouping and allocation, and for OpenAI and Anthropic direct imports enables matching costs already split by API key. | | `identity_id` | String | Optional | AWS (Bedrock) only. IAM principal that made the request (also accepts nested `identity.id`, or legacy `identity_arn` / `identity.arn`). Applies only when your AWS costs use [CUR 2.0 with caller identity (IAM principal) allocation data enabled](/connecting_aws#cur-format): when the principal is present on both sides, Vantage matches by principal and adds a `bedrock:principal` tag. On Legacy CUR it is ignored. | | `provider_region` | String | Optional | Provider region for the request. Available as a grouping and allocation dimension. | | `request_id` | String | Optional | Gateway request identifier. Useful for troubleshooting; not added to allocation dimensions. | | `provider_request_id` | String | Optional | Request identifier assigned by the provider. Useful for troubleshooting; not added to allocation dimensions. | | `tags` | Object | Optional | Custom key/value dimensions for grouping, filtering, and allocating costs. Prefer stable keys with a limited set of values, such as `team`, `environment`, and `purpose`. | #### Tagging Guidance These rules govern how your `tags` and top-level metadata become cost dimensions, and which values to keep out of `tags`. * Top-level `service_tier`, `is_batch`, `provider_region`, `endpoint`, and `api_key_id` values override fields with the same names inside `tags`. * `resource_account_id` must be top-level and cannot be supplied through `tags`. * Keep `request_id`, `provider_request_id`, `flow_run_id`, and similar request identifiers out of `tags`, since they are high-cardinality and are not used as allocation dimensions. * Avoid dimensions with very high cardinality or personally identifiable information (for example, email addresses or conversation identifiers) unless operationally necessary. Never include API key values, credentials, secrets, or other sensitive authentication material in any field or tag. #### Record Validity For a record to be counted, it must describe a successful request with usage Vantage can match to your costs. A record is skipped when: * A required field (`event_id`, `timestamp`, `provider`, `model`, or `usage`) is missing, or the `timestamp` is blank or cannot be parsed. * The `provider` is blank or not a supported value, or the `model` is blank or cannot be matched to your provider cost data. * The `status` is set to anything other than `success` (omit it or leave it blank for successful requests). * No `usage` field contains a positive integer. ### Step 2: Connect the Source in Vantage In Vantage, go to the [Integrations page](https://console.vantage.sh/settings/integrations) and, under **LLM Enrichment**, add **Custom LLM Enrichment**, then select the S3 bucket that holds your telemetry. The connect screen walks you through granting read access and validating it, and connecting then scans your recent logs so you can review which providers were found. You can connect one or more buckets per account. After you connect a bucket, Vantage scans your recent logs and you choose which of your supported provider cost integrations should receive enrichment from that bucket; you can change that selection later from the source's **Edit** screen. Provider cost integrations you connect *after* setting up a source are not enriched automatically; open the source's **Edit** screen and enable the new integration there. Connecting reuses your existing [AWS cross-account IAM role](/connecting_aws#how-vantage-connects-with-aws), adding read-only access to the bucket that holds your telemetry. It does not create a new role or require new credentials. Select the S3 bucket that receives your telemetry. If your bucket does not appear in the list, it may not be synced into Vantage's inventory yet. Newly created buckets can take up to 24 hours to appear. Deploy in the **AWS account that owns the telemetry bucket**, and make sure the bucket ARN in the policy matches the bucket you connect in Vantage. A mismatch is the most common cause of an `access denied` result when you check permissions. The connect screen offers three ways to grant access, each prefilled for your account: The connect screen provides a CloudFormation quick-create link that opens the AWS Console with the stack name, template URL, and parameters prefilled. Acknowledge that CloudFormation may create IAM resources, then create the stack. The stack applies the [Vantage-published template](https://vantage-public.s3.amazonaws.com/vantage-integration-custom-llm-enrichment.json) with two parameters: * `VantageCrossAccountRole`: the name of your existing Vantage cross-account IAM role. * `CustomLlmEnrichmentBuckets`: a comma-separated list of telemetry bucket ARNs, each as `arn:aws:s3:::your-bucket/*`. Deploy the stack in the account that owns the bucket, not necessarily your management/payer account. The connect screen provides a ready-to-run `aws cloudformation create-stack` command using the same template and parameters as the Console method: ```bash theme={null} aws cloudformation create-stack \ --stack-name CustomLLMEnrichmentSourceAccess- \ --template-url https://vantage-public.s3.amazonaws.com/vantage-integration-custom-llm-enrichment.json \ --capabilities CAPABILITY_IAM \ --region us-east-1 \ --parameters \ ParameterKey=VantageCrossAccountRole,ParameterValue= \ ParameterKey=CustomLlmEnrichmentBuckets,ParameterValue=arn:aws:s3:::your-bucket/* ``` Run the command with credentials for the AWS account that owns the bucket. For multiple buckets, pass a comma-separated list of ARNs as a single `ParameterValue`. If you manage your Vantage integration with the [`vantage-sh/vantage-integration/aws`](https://registry.terraform.io/modules/vantage-sh/vantage-integration/aws/latest) module, add the telemetry read permissions through the module's `additional_inline_policies` argument: ```hcl main.tf theme={null} module "vantage-integration" { source = "vantage-sh/vantage-integration/aws" additional_inline_policies = [ { name = "CustomLLMEnrichmentSource-" policy = jsonencode({ Version = "2012-10-17", Statement = [ { Action = ["s3:GetObject", "s3:GetObjectAcl"], Resource = ["arn:aws:s3:::your-bucket/*"], Effect = "Allow" } ] }) } ] } ``` This attaches the policy to your existing cross-account role; it does not create a new role. Bucket listing and location come from the base role, so only object read is added here. See the [Terraform documentation](/terraform#vantage-terraform-integrations-module-for-aws) for base module setup. Whichever method you use, Vantage needs the following read-only access to validate and ingest telemetry: | Permission | When it is needed | | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | | `s3:GetObject` | Read the telemetry objects in the bucket you connect. | | `s3:ListBucket` | List objects under the log path to find your telemetry. | | `s3:GetBucketLocation` | Resolve the bucket's Region. | | `kms:Decrypt` | The bucket or objects are encrypted with AWS KMS (SSE-KMS). Without it, Vantage cannot read KMS-encrypted objects. | Your existing Vantage cross-account role already grants `s3:ListBucket` and `s3:GetBucketLocation`. The grant above adds only object read on the telemetry bucket (`s3:GetObject`, and the generated policy always includes `s3:GetObjectAcl`). The CloudFormation, CLI, and Terraform options above grant S3 read access only. If your telemetry bucket uses SSE-KMS encryption, you must grant `kms:Decrypt` separately. See [KMS-Encrypted Buckets](#kms-encrypted-buckets). Click **Check Permissions**. Vantage validates that it can resolve the bucket Region, list objects, and read a sample object. Then click **Connect**. Vantage confirms the source and immediately scans your recent gateway logs, from the first day of the previous calendar month through today, to detect which providers and provider accounts appear in the bucket. You are taken to a **Scanning gateway logs** page that refreshes on its own; a large bucket can take several minutes. A success message confirms the source is connected and scanning has begun. When the scan finishes, a **Review** action appears for the source. See the [Troubleshooting](#troubleshooting) section for any errors that are displayed. When the scan finishes, select **Review** for the source. The review screen lists each detected provider with its **Valid rows** and **Invalid rows** counts and a **Notes** column that flags issues such as an unsupported provider, gateway logs missing `resource_account_id`, or account IDs that could not be matched to a cost integration. If most of the scanned rows failed validation, a warning suggests confirming that your objects use the common-schema `YYYY/MM/DD/*.jsonl.gz` format and include the required fields (`provider`, `model`, `usage`, and `status`). Choose which connected cost integrations should receive token enrichment from this bucket, then select **Confirm**. Vantage enriches costs for the selected integrations on each provider's next data refresh. You can change the selection later from the source's **Edit** screen. ## Manage Custom LLM Enrichment Sources Manage your connected buckets from the **Custom LLM Enrichment** integration page. The sources table lists each bucket with its AWS account, connection date, and **Status** (for example, **Pending** while a scan or first import is in progress, **Stable** once enrichment has run, **Error** if a scan failed, or **Paused** if the source is stopped). Each row has icon actions to review or edit its integrations, view import history, and stop or restore enrichment. ### Choose Which Integrations Are Enriched After a scan finishes, select **Review** on the source to choose which connected cost integrations receive enrichment (see [Step 2](#step-2-connect-the-source-in-vantage)). To change that selection later, select the **edit** icon (a pencil) in the source's row. The edit screen lists each provider integration with its status, such as **Enabled**, **Paused**, or a count like *2 of 3 enabled* for a provider with multiple accounts, and lets you enable or disable enrichment per integration. Disabling an integration here stops going-forward enrichment for it but leaves its existing enriched history in place. ### View Import History In the sources table, select the **history** icon (a clock with a counterclockwise arrow) in a source's row to open its **Import History**. The screen lists one row per provider cost integration and billing period that ran enrichment, with columns for the **Integration** (with its account beneath), **Status**, **Billing Period**, **Ingested At**, **Log Match Rate**, **Parsed**, and **Skipped**. When a run needs attention (for example, a shared bucket whose logs lack `resource_account_id`), the reason appears in the **Status** column. Lifecycle changes also appear as marker rows: **Added** when enrichment is first enabled for an integration, and **Paused** or **Resumed** when you stop, disable, restore, or re-enable it. ### Stop a Source To stop a source, select the **delete** icon (a trash can) in its row, then confirm in the **Stop enrichment source** dialog. Stopping is a soft deactivation: Vantage stops enriching new cost data for that bucket, but your existing enriched history is left unchanged, and the source stays visible in the list so you can bring it back at any time. Stopping a source does not re-import or roll back already-enriched costs. Going-forward enrichment simply pauses for that bucket until you restore it. ### Restore a Source To restore a stopped source, select the **restore** icon (a trash can with a counterclockwise arrow) in its row. Restore resumes going-forward enrichment for the integrations that were active when you stopped the source (integrations you had already disabled individually stay disabled) and opens the Edit screen so you can adjust the selection. A stopped bucket cannot be re-added through the connect wizard; use Restore instead. ## 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](/cost_reports), [Virtual Tags](/tagging), [Segments](/segments), [Budgets](/budgets), and [Cost Alerts](/cost_alerts). Because enrichment splits (allocates) your provider costs, enrichment tags behave like Vantage's [cost allocation tags](/tagging#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](/tagging#virtual-tag-allocation-rules). Allocated values show the allocated badge (calculator icon) in the console. ### Enrichment Tag Reference | Tag key | Description | Example value | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | *Your `tags` keys* | Every key in a record's `tags` becomes a tag on the enriched rows for that usage slice. | `team`, `purpose`, `environment` | | `model` | The normalized model identifier that generated the cost, derived from the cost row. | `gpt-5.2-2025-12-11` | | `service_tier`, `is_batch`, `provider_region`, `endpoint`, `api_key_id`, `resource_account_id` | Promoted from the top-level telemetry fields when present, so you can group and allocate by them too. | `service_tier=default` | | `bedrock:principal` | AWS (Bedrock) only. The IAM principal that made the request, added when your telemetry includes `identity_id` (or `identity_arn`) and your AWS costs use [CUR 2.0 with IAM principal allocation data](/connecting_aws#cur-format). | `my-role/session-name` | | *Provider's existing tags* | Tags Vantage already puts on the provider's cost rows (for example, the `ai:*` tags) are preserved on the enriched rows. If one of these shares a key with a slice `tag`, the enrichment value wins. | `ai:model` | The keys appear exactly as you emit them, with no provider prefix. For example, on enriched OpenAI costs you would see the key `model` with values like `gpt-5.2-2025-12-11`, and your own keys such as `team` with values like `growth`, not `openai:model` or `openai:team`. Because the key is just `team` (not provider-namespaced), the same key lines up across OpenAI, Anthropic, Azure, and the other providers, so you can group your entire AI stack by one `team` tag. Consistent key naming matters: `team` and `Team` are two different keys. 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 `model` (values like `gpt-5.2-2025-12-11`) or a `tags` key 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](/tagging#preferred-tags) so they sort to the top of these menus. Enriched rows retain the provider's existing tags (for example, Vantage's `ai:*` tags) and add the `model` tag; split rows also carry the `tags` from their usage slice. When a slice `tag` and an existing tag use the same key, the enrichment value wins. The leftover row (usage not covered by telemetry) keeps the provider's existing tags and the `model` tag but carries none of the slice `tags`. Request identifiers (`event_id`, `request_id`, `provider_request_id`, `flow_run_id`) are never turned into tags. ## Troubleshooting Most errors are displayed when you click **Check Permissions** or **Connect**. The tables below list the messages you may see, their cause, and how to resolve them. Expand a section for the relevant category. | Message | Cause and fix | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Vantage cannot determine the location for bucket {bucket}. Grant s3:GetBucketLocation to the cross-account role.` | Add `s3:GetBucketLocation` to the cross-account role. | | `Vantage cannot list objects under s3://{bucket}/{prefix}. Grant s3:ListBucket for the configured prefix.` | Add `s3:ListBucket` scoped to the bucket (and prefix, if used). | | `Vantage cannot read object s3://{bucket}/{key}. Grant s3:GetObject to the cross-account role.` | Add `s3:GetObject` (and `s3:GetObjectAcl`) for the bucket. | | `Vantage cannot decrypt KMS-encrypted object s3://{bucket}/{key}. Grant kms:Decrypt to the cross-account role.` | The bucket uses SSE-KMS. Grant `kms:Decrypt` for the encrypting key. | | `Vantage could not assume the AWS cross-account role. Verify that the role exists, its trust policy allows Vantage to call sts:AssumeRole, and the configured external ID matches.` | Vantage cannot assume your [cross-account IAM role](/connecting_aws#how-vantage-connects-with-aws). Confirm the role still exists, its trust policy allows Vantage's `sts:AssumeRole`, and the external ID matches. | Confirm the permissions were deployed in the **AWS account that owns the bucket**, and that the bucket ARN in the policy matches the connected bucket. | Message | Cause and fix | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Bucket {bucket} does not exist or could not be found.` | The bucket does not exist or is not reachable by the role. Verify the name and account. | | `No objects matching YYYY/MM/DD/*.jsonl.gz were found in s3://{bucket}/{prefix}. Vantage expects files in that date layout.` (or `No objects were found in s3://{bucket}/{prefix}.`) | The bucket has no `.jsonl.gz` objects under the expected `YYYY/MM/DD` path yet, or they use a different layout. Write a test record in the expected layout and wait for delivery, then re-check. | | `Vantage scanned 3000 objects in s3://{bucket}/{prefix} but could not find a matching log file. Use a dedicated bucket or a more specific prefix.` | Vantage scanned the first objects under the path without finding a matching log file. Point the source at a dedicated bucket or a more specific prefix so telemetry is found quickly. | | `Permission check timed out. The bucket may be large, or logs may not use the expected date layout.` | The permission check did not finish in time. Narrow the source to a dedicated bucket or prefix, confirm the `YYYY/MM/DD/*.jsonl.gz` layout, then re-check. | | `Bucket {names} could not be found for your account.` | The selected bucket is not in Vantage's synced inventory. Newly created buckets can take up to 24 hours to appear. | | `Connect an AWS, Anthropic, Azure, GCP, or OpenAI cost integration before checking Custom LLM enrichment permissions.` (the Connect action shows `...before connecting Custom LLM enrichment.`) | No enrichable cost integration exists. Connect a supported provider first. | Enrichment can only split costs by dimensions present in your telemetry. Costs pass through without allocation splits when any of the following is true: * There is no active Custom LLM Enrichment source for the account, or the telemetry has not been ingested for that billing period. * The cost row's model or token type could not be matched to a logged request for that provider, date, and token kind. * Records were skipped during ingestion because a required field was missing or invalid, the `provider` was blank or unsupported, the `model` was blank or could not be matched to your provider cost data, the `status` was not successful, or no `usage` value was a positive integer. Confirm your records set `provider` to an [accepted value](#step-1-emit-telemetry-in-the-common-schema), carry a matching `model`, and include at least one positive usage count. 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). ### KMS-Encrypted Buckets If your telemetry bucket is encrypted with AWS Key Management Service (KMS), **Check Permissions** reports a decryption error until Vantage can read the objects. Either remove encryption on the bucket, or grant the cross-account role `kms:Decrypt` for the encrypting key and allow that role in the KMS key policy. The CloudFormation, CLI, and Terraform options in [Step 2](#step-2-connect-the-source-in-vantage) grant S3 read access only, so KMS access must be added separately. ## Use Cases Each row below shows example `tags` to emit on your telemetry and what that attribution enables in Vantage. The key names are examples; you choose your own, and Vantage surfaces whatever `tags` you send. All rows assume telemetry is delivered to a connected bucket. | Use Case | Emit in `tags` | What It Enables | | ----------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chargeback by team | `team` | Group a [Cost Report](/cost_reports) by `team` for per-team LLM chargeback, or roll `team` values into a business hierarchy with a [Virtual Tag](/tagging). | | Per-user attribution on shared keys | `user` | Attribute spend to the individual who made each request even when many callers share one API key, which the provider bill cannot break apart. | | Per-feature or per-workflow spend | `feature`, `workflow` | Compare cost per product feature or workflow (for example, `summarization` vs. `classification`). | | Model and effort mix | `mode`, `effort` | Spot macro patterns (which models and effort levels dominate spend) and outliers to guide defaults. The `model` tag is added automatically, so you do not need to emit it. | | Environment separation | `environment` | Filter non-production inference out of showback reports, or budget each environment (`production`, `staging`) separately. | ## Frequently Asked Questions OpenAI, Anthropic, AWS Bedrock, Google Cloud (Vertex AI Gemini and Marketplace Claude), and Azure OpenAI. You deliver one telemetry stream in the common schema, and Vantage routes each record to the matching provider's costs based on its `provider` value. Azure support covers direct Azure (Azure OpenAI) integrations; Azure CSP billing accounts are not supported. You need the **Organization Owner** or **Integration Owner** role. See [Role-Based Access Control](/rbac). Read-only access to the telemetry bucket you connect: `s3:GetObject`, `s3:ListBucket`, `s3:GetBucketLocation`, and `kms:Decrypt` for KMS-encrypted objects (generated policies may also include `s3:GetObjectAcl`). The policy attaches to your existing cross-account role; no new role is created. See [Step 2: Connect the Source in Vantage](#step-2-connect-the-source-in-vantage). No. You emit the telemetry yourself, so this works for direct-to-provider traffic (for example, calling OpenAI or Anthropic APIs directly) as well as traffic behind a gateway. The only requirement is that you write common-schema records to S3. 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. No. Enrichment is metadata-only. The telemetry stream carries request identifiers, the provider and model, usage counts, and the allocation `tags` you choose to emit. Prompt and completion text are never collected or stored.