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, Virtual Tags, Segments, Budgets, and 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 Source 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.
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. 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: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: 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.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:$100 row becomes three rows:$100. The leftover row carries the portion of the cost row’s tokens that your telemetry does not cover; it keeps 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 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, Anthropic, AWS, Google Cloud, or Azure.
- An active AWS integration (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.
Set Up the Custom LLM Source
Setup has two steps: emit your telemetry in the common schema to S3 and connect the source in Vantage, which is also where you grant Vantage read access to the bucket.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:- Use the request timestamp’s UTC date for the
YYYY/MM/DDpartition. - Place the logs at the bucket root or under any prefix (subfolder); keep the
YYYY/MM/DDdate 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.
tags and top-level metadata become cost dimensions, and Record validity covers what makes a record count.
Core Fields
These fields are required on every record.Accepted provider values
Accepted provider values
provider to the identity that matches your cost integration.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
Theusage 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.
uncached_input_tokens is omitted or null, Vantage derives it as:
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.
Tagging Guidance
These rules govern how yourtags and top-level metadata become cost dimensions, and which values to keep out of tags.
- Top-level
service_tier,is_batch,provider_region,endpoint, andapi_key_idvalues override fields with the same names insidetags. resource_account_idmust be top-level and cannot be supplied throughtags.- Keep
request_id,provider_request_id,flow_run_id, and similar request identifiers out oftags, 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.
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, orusage) is missing, or thetimestampis blank or cannot be parsed. - The
provideris blank or not a supported value, or themodelis blank or cannot be matched to your provider cost data. - The
statusis set to anything other thansuccess(omit it or leave it blank for successful requests). - No
usagefield contains a positive integer.
Step 2: Connect the Source in Vantage
In Vantage, go to the Integrations page and, under LLM Enrichment, add a Custom LLM Source, then select the S3 bucket that holds your telemetry. The connect screen walks you through granting read access and validating it.Select the bucket
Grant Vantage read access
- AWS Console
- AWS CLI
- Terraform
VantageCrossAccountRole: the name of your existing Vantage cross-account IAM role.CustomLlmEnrichmentBuckets: a comma-separated list of telemetry bucket ARNs, each asarn:aws:s3:::your-bucket/*.
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).kms:Decrypt separately. See KMS-Encrypted Buckets.Check permissions and connect
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, Virtual Tags, Segments, Budgets, and Cost Alerts. Because enrichment splits (allocates) your provider costs, enrichment tags behave like Vantage’s 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. Allocated values show the allocated badge (calculator icon) in the console.Enrichment Tag Reference
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 likegpt-5.2-2025-12-11) or atagskey such asteam. - To filter: open the Filters menu, click New Rule, select Tag, choose the Tag Key, then pick an operator and one or more values.
tags from their usage slice plus the model tag; they do not retain other provider tags on those split rows. The leftover row (usage not covered by telemetry) carries only the model tag. 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.Permission and access errors
Permission and access errors
Bucket and telemetry errors
Bucket and telemetry errors
My costs are not being split
My costs are not being split
- There is no active Custom LLM 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
providerwas blank or unsupported, themodelwas blank or could not be matched to your provider cost data, thestatuswas not successful, or nousagevalue was a positive integer.
provider to an accepted value, carry a matching model, and include at least one positive usage count.My totals changed after enabling enrichment
My totals changed after enabling enrichment
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 rolekms:Decrypt for the encrypting key and allow that role in the KMS key policy. The CloudFormation, CLI, and Terraform options in Step 2 grant S3 read access only, so KMS access must be added separately.
Use Cases
Each row below shows exampletags 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.
Frequently Asked Questions
Which providers are supported?
Which providers are supported?
provider value. Azure support covers direct Azure (Azure OpenAI) integrations; Azure CSP billing accounts are not supported.What Vantage permissions do I need to enable this?
What Vantage permissions do I need to enable this?
What access does Vantage gain in my AWS account?
What access does Vantage gain in my AWS account?
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.Do I need an AI gateway to use this?
Do I need an AI gateway to use this?
Will this change my totals or break existing reports?
Will this change my totals or break existing reports?
Does Vantage see my prompt content?
Does Vantage see my prompt content?
tags you choose to emit. Prompt and completion text are never collected or stored.