A budget caps AI Gateway spend at one of four scopes:
- Team: everything your team spends, across every project and key.
- Project: what one project's deployments spend, through their OIDC tokens.
- API key: what one API key spends.
- User: what one team member spends, across every API key attributed to them.
AI Gateway checks every budget in scope before each request and rejects further requests once a limit is exceeded, until the budget resets or you raise it. Budgets are optional, and a team, project, key, or member without one has unlimited spend.
To create, view, or delete the API keys themselves, see API Keys.
How budgets work
Budgets stack, and which ones apply depends on how a request authenticates. A request has to pass every budget in scope, so if any one is exceeded, AI Gateway rejects the request even when the others have room.
Our Services
What one request counts toward
Request with an OIDC token
from a project's deployment
Team budget
Request with an API key
attributed to a team member
+$1
Project budget
The auth type picks the lane; the cost lands on every budget in the lane at once.
+$1
API key budget
the member
User budget
Software Delivery
A request has to pass every budget in its lane. If any one of them is exhausted, AI Gateway rejects the request, even when the others have room.
+$1
+$1
Team budget
+$1
Take a team with all four budget scopes in use:
Budget in scope
Team acme
Project storefront in team acme
Limit
$100
Spent this period
$100
API key, attributed to member teammate
Member teammate (user budget)
$50
$40
$10
$10
Request
A deployment in storefront, using its OIDC token
Two requests against that team get different outcomes:
Budgets in scope
Outcome
The totals above are cumulative, so they overlap rather than add up. The team's $110 is the project's $100 plus the key's $10, because each of those requests also counted toward the team. The key's $10 and teammate's $10 are the same $10, counted once against the key and once against the member it is attributed to.
Any request using the API key
Each budget counts a specific set of authentication types:
Team, project
Team, API key, user
Rejected. The project budget is exhausted.
Succeeds. No project budget applies, and the rest have room.
- Team budget: API keys, OIDC tokens, app tokens, and personal access tokens
- Project budget: OIDC tokens from that project's deployments
- API key budget: that one API key
- User budget: API keys attributed to that team member
- No budget: BYOK provider keys
An API key's spend is never attributed to a project, no matter which project uses the key. Spending down a project budget requires an OIDC token from that project's deployments.
Each API key is also attributed to either your team or the member who created it. A key attributed to a member counts its spend toward both the team budget and that member's user budget; a key attributed to the team counts toward the team budget only. Only API keys carry this attribution, so OIDC tokens, personal access tokens, and app tokens never count toward a user budget. See Spend attribution to set it.
A default budget is a catch-all cap for one scope, with one default for projects, one for API keys, and one for team members:
- It applies to every project, key, or member without a custom budget, including ones that already exist and ones added later.
- Each covered resource gets its own allowance. A $50 API key default caps every covered key at $50 per period; it isn't $50 split across them.
- It never overrides a custom budget. The custom budget wins whether you set it before or after the default.
- Metering starts when the default takes effect. Spend from before that point doesn't count against it, so a key that has already spent $10,000 starts at $0 against a new $40 default.
Our Services
Set on the resource itself. When one exists, it is the resource's cap and the default is ignored.
Custom budget
One per scope; each covered resource gets its own allowance. Yields to a custom budget.
How a budget is resolved
Team member
The same chain applies to a project, an API key, or a team member.
Project
none set
Applies to every request on top of whichever tier resolved, when one is set.
Scope default
$100 a month
API key
Spend is limited only by the layer below.
No cap of its own
Team budget
none set
Wins
$50 a month
Default
monthly
Each refresh period resets at the start of its window in UTC:
Period
daily
Resets at
Midnight UTC each day
Never resets; the limit is cumulative
A default carries a limit and a refresh period only. It doesn't send spend alerts; set a custom budget on a resource to get alerts for it.
weekly
none
Monday at midnight UTC
Removing a default lifts that cap from every resource it covered. After that, only the team budget still applies to them, if you've set one.
The first of the month at midnight UTC
When a budget is exceeded
Editing a budget keeps the spend already accumulated in the current period. Deleting a budget removes that cap immediately. A project, key, or member covered by a default budget falls back to the default rather than becoming unlimited. Re-creating a budget later starts metering from that point, not retroactively.
Once spend reaches the limit, AI Gateway rejects further requests for that scope with an HTTP 402 response until the budget resets or you raise it. The type is always quota_for_entity_exceeded, and the message names the scope that was exceeded along with its current spend and limit.
A team or project budget:
{
}
}
"error": {
"type":"quota_for_entity_exceeded"
"message":"Project budget exceeded. Current spend: $200.00, limit: $200.00. Please contact your administrator to increase the budget."
{
}
"error": {
"type":"quota_for_entity_exceeded"
}
"message":"Quota limit exceeded for \"api_key_id_
A user budget rejects the same way once a member's user-attributed keys exceed it, with the message naming the user scope.
Handle a 402 in your client by backing off until the budget resets, or raise the limit.
SDK error classes can differ from the HTTP status. A budget rejection can surface as GatewayInternalServerError in AI SDK 7 or ProviderInternalServerError in the Python beta. Check the quota details before retrying. See AI SDK error handling for handling SDK exceptions and streaming errors.
Spend alerts
Spend alerts email someone as spend crosses a chosen percentage of the limit within a refresh period. They are off by default. When you add or edit a team, project, API key, or user budget, pick any combination of 50%, 75%, and 100% under Email ... when usage reaches. Each threshold you select fires at most once per period.
Who receives the email depends on the budget's scope:
Budget scope
API key
Alerts go to
The key's creator
Team owners and members with the Billing role
Every team role except Contributor can see budgets. Owner, Member, Developer, Security, Viewer, and Billing all have read access to the Budgets page and its tabs.
Team or project
Alerts are informational. Crossing a threshold below 100% never blocks requests.
The team member whose budget it is
Writing is more restricted. Besides the Owner role, an Owner can grant a member the AI Gateway Budget Manager permission from the team's member settings; it covers every budget action below without the rest of the Owner role.
Action
View every budget, default, and spend
Create, edit, or remove the team budget
Create, edit, or remove a project budget
Owners and Budget Managers
Owners and Budget Managers
Every team role except Contributor
Owners, Budget Managers, and that project's admins
Create, edit, or remove a user budget
Set or remove a default budget (project, API key, or user)
Change a key's spend attribution
Owners and Budget Managers
Owners and Members (anyone who can edit the key)
Owners and Budget Managers
API key budgets are the one exception to the Budget Manager grant. They follow key-editing permission, so a Budget Manager changes them through their base role rather than the grant.
These rules apply the same way whether you use the dashboard or the CLI.
Team and project budgets
The two scopes are independent, and you can use either or both:
- A team budget caps all AI Gateway spend across your team for the refresh period. When it is exceeded, every gateway request from your team is rejected until the budget resets.
- A project budget caps the spend attributed to one project. When it is exceeded, only that project's requests are rejected; the rest of your team is unaffected.
- Choose the scope. Open the Team tab for a team budget, or the Projects tab to pick a project.
- Add the budget. Click Add budget, enter a spending limit in dollars, and choose a refresh period.
- Save. The budget takes effect within a few minutes.
- Find the budget. Open the Team tab or the Projects tab.
- Open the budget's menu. Find the budget and open its ··· menu.
- Edit or remove. Select Edit budget to change the limit, refresh period, or spend alerts. Select Remove budget to lift the cap.
A default budget applies to every project without a custom budget, including projects that already exist. Setting a custom budget on a project overrides the default; see Default budgets for the full semantics. API keys have a separate default, covered in API key default budgets.
- Open the projects tab. Go to the Projects tab of the AI Gateway Budgets page.
- Set the project default. Click Set Default (or the current default value, if one is set) and enter a spending limit in dollars and a refresh period in the Project Default dialog.
- Save. Every project without its own budget now inherits this limit, shown as Default in the projects list.
API key budgets
An API key budget caps how much a single key can spend, independently of any team or project budget. You manage it from the API Keys page or the CLI.
Set an API key budget at creation
Add a budget at the time you create the key:
- Open the create-key dialog. On the AI Gateway API Keys page, click Create key.
- Enable a budget. Turn on the budget option and enter a spending limit in dollars.
- Choose a refresh period. Select how often the budget resets (see refresh periods).
- Save the key. Save the key, and copy its value immediately. You cannot retrieve it again.
On the API Keys page, a budgeted key shows its spend against the limit (for example, $1.04 / $10 spent) with the refresh period. A key without a budget shows Unlimited budget.
To compare every key's budget in one place, use the API Keys tab of the Budgets page.
Add or change an API key budget
Give an existing key a budget, or change the one it has, from the dashboard or the CLI.
- Open the API Keys page. Go to the AI Gateway API Keys page.
- Edit the key. Find the key, open its ··· menu, and select Edit key.
- Add or change the budget. Enable or update the budget, set the limit and refresh period, and save.
Removing a budget lifts that key's own cap. A key covered by the API key default falls back to it; otherwise the key reverts to unlimited.
- Open the API Keys page. Go to the AI Gateway API Keys page.
- Edit the key. Find the key, open its ··· menu, and select Edit key.
- Remove the budget. Turn off the budget and save. The key falls back to the API key default if your team has one, and is otherwise unlimited.
A default budget applies to every API key without a custom budget, including keys that already exist. Setting a custom budget on a key overrides the default; see Default budgets for the full semantics.
- Open the API Keys tab. Go to the API Keys tab of the AI Gateway Budgets page.
- Set the API key default. Click Set Default (or the current default value, if one is set) and enter a spending limit in dollars and a refresh period in the API Key Default dialog.
- Save. Every key without its own budget now inherits this limit.
User budgets
A user budget caps how much a single team member can spend, across every API key attributed to that member. It stacks with the team budget, so a member's request has to pass both their user budget and the team budget.
- Open the Users tab. Go to the Users tab of the AI Gateway Budgets page.
- Add the budget. Click Add budget, pick a team member, enter a spending limit in dollars, and choose a refresh period.
- Save. The budget takes effect within a few minutes.
You can reach our customer support team by emailing info@yourcompany.example.com, calling +1 555-555-5556, or using the live chat on our website. Our dedicated team is available 24/7 to assist with any inquiries or issues.
We’re committed to providing prompt and effective solutions to ensure your satisfaction.
We offer a 30-day return policy for all products. Items must be in their original condition, unused, and include the receipt or proof of purchase. Refunds are processed within 5-7 business days of receiving the returned item.
Dashboard
Change or remove a user budget
CLI
- Open the Users tab. Go to the Users tab of the AI Gateway Budgets page.
- Set the user default. Click Set Default (or the current default value, if one is set) and enter a spending limit in dollars and a refresh period in the User Default dialog.
- Save. Every member without their own budget now inherits this limit.
A default budget applies to every team member without a custom budget, including members who join later. Setting a custom budget on a member overrides the default; see Default budgets for the full semantics.
Budgets limit usage; they do not reserve or purchase capacity. Your team still needs credits or a payment method to make requests.
Last updated September 10, 2026
BYOK spend isn't counted in
budgets. Spend that draws on your own provider keys is metered separately and
doesn't count toward any limit.
Previous
Was this helpful?
Cross-link map: AI Gateway Budgets and Spend Limits (/docs/ai-gateway/observability-and-spend/budgets)From the Vercel docs graph (built 2026-09-21T05:26:59.511Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.jsonSemantically closest pagesAI Gateway now supports team and project spend budgetsBudgets for API keys on AI GatewayAI Gateway API Keys — Create, view, and delete AI Gateway API keys, and set each key's budget and spend attribution, from the dashboard, CLI,Set per-user budgets on AI GatewayHow to route your coding agent spend through AI Gateway — Point Claude Code, Codex, Cursor, and every other harness on your machine at AI Gateway with one CLI command, on a budgeThis page links to (10)Error HandlingAI Gateway API Keys — Create, view, and delete AI Gateway API keys, and set each key's budget and spend attribution, from the dashboard, CLI,Bring Your Own Key \(BYOK\) to AI Gateway — Learn how to configure your own provider keys with AI Gateway.AI Gateway OIDC Authentication — Authenticate AI Gateway requests from Vercel deployments with OIDC tokens. Configure the AI SDK or send bearer tokens diAI Gateway Pricing — Understand AI Gateway token pricing, free and paid credits, BYOK costs, add-on charges, and payment fees. Manage creditvercel ai-gateway — Manage AI Gateway resources from the Vercel CLI: API keys, budgets, routing rules, virtual models, models, leaderboards,vercel tokens — Manage your personal Vercel authentication tokens from the CLI: list, create, and remove access tokens for use with theTeam Level Roles — Learn about the different team level roles and the permissions they provide.Managing Team Members — Learn how to manage team members on Vercel, and how to assign roles to each member with role-based access control \(RBACTokens — Learn how to Sign in with VercelPages that link here (42)By site: vercel-changelog (4) · vercel-kb (3) · vercel-docs (35)From vercel-changelogAI Gateway now supports team and project spend budgetsSet per-user budgets on AI GatewaySet up coding agents in one command with AI GatewayTypeSafe AI's Jev now available on AI GatewayFrom vercel-kbRun recurring security reviews with deepsec on Vercel — Learn how to run periodic security scans on your code with deepsec. Set up deepsec to review GitHub repositories and delHow to build your own AI model router — Build an AI model router with Vercel AI Gateway. Keep routing, key, and retention decisions in your code while the gatewHow to classify, route, and score with Jev and AI SDK — Use Jev from TypeSafe AI with AI SDK's experimental \evaluate\\ API to classify, route, score, and verify inside your aFrom vercel-docsVercel AI Gateway: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, rAI Gateway Authentication and BYOK — Authenticate AI Gateway requests with API keys or OIDC tokens, and configure bring your own key \(BYOK\) credentials forAI Gateway API Keys — Create, view, and delete AI Gateway API keys, and set each key's budget and spend attribution, from the dashboard, CLI,Bring Your Own Key \(BYOK\) to AI Gateway — Learn how to configure your own provider keys with AI Gateway.Aider with AI Gateway — Connect Aider to AI Gateway with the Vercel CLI or an OpenAI-compatible base URL, API key, and model metadata.Amp with AI Gateway — Connect Amp to AI Gateway through Amp's Model Routing settings. Add an AI Gateway API key, choose models for Amp's modesContinue CLI with AI Gateway — Connect Continue CLI to AI Gateway with the Vercel CLI or a YAML model configuration that reads your API key from the enGitHub Copilot CLI with AI Gateway — Connect GitHub Copilot CLI to AI Gateway with the Vercel CLI or environment variables for the provider URL, API key, andCursor with AI Gateway — Connect Cursor to AI Gateway with its OpenAI base URL override. Configure the Cursor compatibility endpoint, API key, anDeep Agents CLI with AI Gateway — Connect Deep Agents CLI to AI Gateway with the Vercel CLI or a TOML provider and model profiles.DeepSeek Harness with AI Gateway — Connect DeepSeek Harness to AI Gateway with the Vercel CLI or a YAML provider and model shortlist.Factory Droid with AI Gateway — Connect Factory Droid to AI Gateway with the Vercel CLI or bring-your-own-key custom model entries.ForgeCode with AI Gateway — Connect ForgeCode to AI Gateway with the Vercel CLI or custom provider and credential files.fx with AI Gateway — Connect fx to AI Gateway with the Vercel CLI or the AI_GATEWAY_API_KEY environment variable.Goose with AI Gateway — Connect Goose to AI Gateway with the Vercel CLI or a custom OpenAI-compatible provider.gptme with AI Gateway — Connect gptme to AI Gateway with the Vercel CLI or a TOML provider configuration.Harbor with AI Gateway — Evaluate coding-agent harnesses with Harbor and AI Gateway. Choose a harness, configure its connection, and pass separatHermes with AI Gateway — Connect Hermes to AI Gateway with the Vercel CLI or manual provider configuration. Set your API key, discover models, anJunie CLI with AI Gateway — Connect Junie CLI to AI Gateway with the Vercel CLI or custom model profiles.Kilo Code with AI Gateway — Connect Kilo Code to AI Gateway with the Vercel CLI or an OpenAI-compatible provider configuration. Set your API key andKimi CLI with AI Gateway — Connect Kimi CLI to AI Gateway with the Vercel CLI or a TOML provider and model shortlist.omp with AI Gateway — Connect omp \(oh-my-pi\) to AI Gateway with the Vercel CLI or an environment variable. Use the built-in provider to acceOpenClaw with AI Gateway — Connect OpenClaw to AI Gateway with the Vercel CLI or manual provider configuration. Use gateway models across coding agOpenHands with AI Gateway — Connect OpenHands to AI Gateway with the Vercel CLI or an OpenAI-compatible LLM configuration.Pi with AI Gateway — Connect Pi to AI Gateway with one CLI command, or configure it manually.Qwen Code with AI Gateway — Connect Qwen Code to AI Gateway with the Vercel CLI or OpenAI-compatible model provider entries.Mistral Vibe with AI Gateway — Connect Mistral Vibe to AI Gateway with the Vercel CLI or a TOML provider and model shortlist.ZCode with AI Gateway — Connect ZCode to AI Gateway with the Vercel CLI or an OpenAI-compatible custom provider.Zed with AI Gateway — Connect Zed to AI Gateway with the Vercel CLI or its built-in Vercel AI Gateway provider.Xcode with AI Gateway — Connect Xcode's AI chat to AI Gateway through the Chat Completions API. Configure the provider, API key, and models in XAI Gateway FAQ — Answers to common questions about AI Gateway, including request errors, pricing and markup, SDK and API compatibility, mAI Gateway Observability and Spend — Monitor AI Gateway requests and control costs with logs, generation lookup, custom reporting, budgets, and OpenTelemetryAI Gateway Pricing — Understand AI Gateway token pricing, free and paid credits, BYOK costs, add-on charges, and payment fees. Manage creditAI Gateway Rate Limits — Learn how AI Gateway rate limits work on the free and paid tiers, what the 429 response looks like, and how to retry a rAI Gateway SDKs and APIs — Connect to AI Gateway with the AI SDK, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and Cohere
