Guides

Guide

Vercel AI Gateway cost tracking by customer, feature and team

Published

Vercel AI Gateway lets you call many AI providers through one key, and Vercel keeps a daily spend report for it. That report doesn't say which of your customers a call served. This guide shows how to tag each Gateway call with a customer, feature and team, bring Vercel's spend report in next to it, and cap the spend.

What does Vercel AI Gateway's own spend report show, and what's missing?

Vercel keeps a daily spend report for your team's Gateway traffic, per model and per day, with optional breakdowns by tag, by user, by API key and by own keys versus Vercel credits. What it doesn't show is your business: which of your customers each call served.

Provider invoices and usage exports have no customer field. They know a key spent money on a model today, not whether that was one customer running a heavy report or a thousand customers sending one message each. The only place that information exists is your code, at the moment it calls the Gateway, so that is where tracking has to start.

How do you track Vercel AI Gateway costs per customer, feature and team?

Record each Gateway call with Token Meter's SDK and tag it with the customer, feature and team when you make it. With the Vercel AI SDK, add Token Meter's middleware to the model. With the OpenAI SDK pointed at the Gateway, use the OpenAI-compatible wrapper. Either way the call is recorded as Vercel AI Gateway.

Open an action() scope around the calls it covers; every metered call inside it gets the tags. Usage is read from the reply the Gateway already sent, so there is no proxy and no extra network hop, and the SDK never throws into your code during a call. Save your Gateway key as AI_GATEWAY_API_KEY and your Token Meter ingest key as TOKEN_METER_KEY.

gateway-call.mjs
import { gateway, generateText, wrapLanguageModel } from "ai";
import { TokenMeterClient, tokenmeterMiddleware, action } from "@tokenmeter/sdk";

const tl = new TokenMeterClient({ apiKey: process.env.TOKEN_METER_KEY ?? "" });

const model = wrapLanguageModel({
  model: gateway("anthropic/claude-sonnet-4.5"), // reads AI_GATEWAY_API_KEY
  middleware: tokenmeterMiddleware(tl),
});

const { text } = await action("generate-report", { customerRef: "acme", feature: "reports", team: "growth" }, () =>
  generateText({ model, prompt: "Say hello in five words." }),
);
console.log(text);

await tl.flush();
AI SDK middlewareOpenAI-compatible wrapper
LanguageTypeScript only, AI SDK versions 3 to 7.Python and TypeScript.
How you call the Gatewaygateway(...) models, wrapped with wrapLanguageModel.The OpenAI SDK with base URL https://ai-gateway.vercel.sh/v1 and provider vercel_gateway.
Cache and reasoning tokensRecorded on AI SDK 5 and later, when the provider reports them.Recorded when the provider reports them.
Gateway reporting tagsOptional, with gatewayReportingTags (AI SDK 5 or later).Not sent for you, in either language: send the ai-reporting-tags header yourself.

The middleware keeps Vercel's creator/model name. Recorded Gateway calls are priced from Vercel's public model list, synced daily. A long-running app sends usage on its own, every 2 seconds or every 500 calls, whichever comes first; the call shows on Requests within a few seconds. A call with no tags still counts in every total; it just can't be split by customer.

On Vercel functions. Vercel freezes a function as soon as it returns a response, so the background send may never run. In TypeScript, create the client with createServerlessClient instead of new TokenMeterClient, then send the usage at the end of every request: in Next.js 15.1 or later with after(() => tl.flush()), and in other Vercel functions by passing the waitUntil from @vercel/functions to flushOnWaitUntil. In Python, call tokenmeter.flush(deadline_s=2.0) as the last line before the handler returns. The TypeScript SDK doesn't run on the Vercel Edge runtime; use the Node.js runtime for routes that call AI models.

Details: Frameworks and runtimes, Attribution and Providers. To turn per-customer cost into margin, see LLM cost per customer.

How do you check the figures against Vercel's spend report?

Connect the report with a Vercel AI Gateway API key and your team slug. Token Meter then reads your team's Gateway spend every hour, per model and per day, and shows it as its own provider, next to the cost the SDK recorded for the same days.

You need to be an Owner or Admin in Token Meter, and your Vercel team must be on the Pro or Enterprise plan, because the connection uses Vercel's Custom Reporting API. A Hobby or Pro trial key is refused when you connect.

  1. In Vercel, open the team you want to report on, then AI Gateway › API Keys, and create a key. The key reads spend for the whole team.
  2. Note the team slug: the part after vercel.com/ in the team's address.
  3. In Token Meter, open Settings › Connections and choose Connect an account. Under Provider, choose Vercel AI Gateway.
  4. Enter the Vercel team slug and paste the key into AI Gateway API key. To rename the connection, open Advanced and change Connection name.
  5. Optionally tick Extra breakdowns: by tag, by user, by API key, and own keys vs Vercel credits. Read the cost note below first.
  6. Choose Connect and sync. Token Meter checks the key, then the card shows Syncing… until the last week has landed, and Filling in older history… while the rest imports, up to 90 days.

The key only reads billing and usage data; Token Meter never uses it to make AI calls. Days are in UTC and today is never requested. Each sync reads the last 3 days again, so Vercel's corrections replace older figures.

Vercel bills each report query

Vercel charges your team $5 per 1,000 report queries. Each sync makes 1 query plus 1 per day with traffic in the last 3 days, so at most 4. Syncs run up to once an hour: at most 96 queries a day, about $0.48 a day or $15 a month. Each extra breakdown adds 1 query per day with traffic, up to 3 more per sync (about $0.36 a day). Backfill history also makes billed report queries.

Reading the comparison. On Analytics › Spend, filter to Vercel AI Gateway. Each model in Vercel's report shows the SDK's recorded cost for the same days beside it, and a model the SDK recorded that is missing from the report is listed as such. Every imported report row, with its period, tokens, requests and spending, is on Data health › Provider usage under Imported reports.

This is a side-by-side view, not invoice reconciliation. On the AI Bill's provider table, a provider with an account report and no invoice reads Not comparable: account reports are not suitable for invoice reconciliation. See AI Bill and billing imports.

How do you line up Vercel's tag report with Token Meter's tags?

Turn on gatewayReportingTags in the middleware. It sends each call's team, project, feature and environment to the Gateway as reporting tags, such as team:payments and env:prod, so Vercel's tag breakdown uses the same names as Token Meter. In Python, send the ai-reporting-tags header yourself.

gateway-tags.mjs
import { gateway, generateText, wrapLanguageModel } from "ai";
import { TokenMeterClient, tokenmeterMiddleware } from "@tokenmeter/sdk";

const tl = new TokenMeterClient({ apiKey: process.env.TOKEN_METER_KEY ?? "" });

const model = wrapLanguageModel({
  model: gateway("anthropic/claude-sonnet-4.5"), // reads AI_GATEWAY_API_KEY
  middleware: tokenmeterMiddleware(tl, { team: "payments" }, { gatewayReportingTags: true }),
});

// Sends ai-reporting-tags: team:payments (plus project:, feature:, env: when set).
const { text } = await generateText({ model, prompt: "Say hello in five words." });
console.log(text);

await tl.flush();
  • It is off by default, because Vercel charges for each tag written ($0.075 per 1,000).
  • Customer references are never sent to the Gateway.
  • It needs AI SDK 5 or later and only touches Gateway models.
  • It keeps any tags you already send and stays within Vercel's limit of 10 tags.
  • With the tag option ticked under Extra breakdowns, Vercel's tag breakdown appears on Analytics › Spend when you pick Vercel AI Gateway in the provider row, under its model list. It is never added to the Gateway's total, because a request counts under every tag it carries.

Customer cost stays on Token Meter's side: it comes from the action() tags, not from Vercel's report.

How does the AI Bill count Vercel AI Gateway spend?

Vercel AI Gateway's report is an account report in US dollars, and it counts toward your total AI spend. For a provider with no invoice lines but a US dollar account report, the AI Bill adds the report's spend, plus metered spend on days the report doesn't reach yet.

Each provider counts once: its invoice, else its account report, else its metered estimate. A provider is never counted from two sources for the same day. The metered part appears on Analytics › Bill as "of which tracked, on days the reports do not cover yet". Only report periods that lie fully inside the range you pick are added; a period is never split.

Illustrative numbers

A made-up month: Vercel's report covers the first 16 days with $300.00 of Gateway spend, and the SDK recorded $12.00 of Gateway calls on the two days after that. The Provider account reports line adds $312.00 for Vercel AI Gateway, of which $12.00 is tracked on days the report does not cover yet. Once the report reaches those days, its own figure replaces the metered one.

  • The Gateway shows as its own provider, kept apart from any direct OpenAI or Anthropic connection, so the same request is never counted twice.
  • Requests that use your own provider keys (BYOK, "bring your own key") show as $0 in Vercel's report, because that spend is billed on your provider account. Connect that provider directly under Settings › Connections to see it. The own-keys breakdown shows the list value of that traffic.
  • On the By provider table, the Account report column shows account-report spend for whole periods in the range.

If the Gateway is one of several AI bills, see tracking AI spend across providers.

How do you cap Vercel AI Gateway spend?

Set a budget and alert rules in Token Meter. A budget is a monthly spend limit on the whole workspace or on one customer, feature, action, team, environment, provider or model. Token Meter checks it every 60 seconds against spend so far this UTC calendar month and warns you as spend nears the limit.

  • Budgets. Thresholds default to 50%, 80% and 100%, each firing once a month, and a projection alert warns when the month's linear burn would end above the budget. Owners and admins create them under Governance › Budgets.
  • Threshold rule. Fires when spend for a scope, optionally limited to one provider and model, reaches an amount within the UTC day or month.
  • Provider spike rule. Fires when today's spend so far for one provider reaches a set multiple of yesterday's total, scaled to the part of the day that has passed.
  • Anomaly (runaway trace). Fires when one trace makes far more calls, or costs far more, than usual for its action.

Alerts go to email, Slack or Discord channels. On the Free plan you can set one advisory, workspace-wide budget; scoped budgets, alert rules and notification channels need a paid plan. See Governance and alerts.

Alerts, not a hard stop

A budget can only stop calls that go through Token Meter's Router. SDK-reported usage and imported bills, which is how Gateway calls reach Token Meter in this guide, count toward a budget and its alerts but can't be blocked this way.

What doesn't this cover?

  • Gateway calls the SDK doesn't see, for example from a framework that creates its own client, appear only in Vercel's imported report, with no customer or feature.
  • Own-key (BYOK) Gateway requests are $0 in Vercel's report; their cost is on your provider's bill.
  • The spend report needs a Vercel Pro or Enterprise team.
  • Report figures are not live: today is never imported, and the newest days can lag while Vercel settles them.
  • An account report is shown beside metered cost, not reconciled against it like an invoice.
  • On AI SDK 3 and 4, cache and reasoning counts stay empty. The total cost is still right; the cache discount and reasoning split are only exact on version 5 and later.
  • The TypeScript SDK doesn't run on the Vercel Edge runtime.

Start tracking Vercel AI Gateway costs

Create a workspace, add an ingest key, add the middleware or wrapper to your Gateway calls and tag one call with a customer and feature. Then connect Vercel's spend report to see it next to the recorded cost.