资产生成 Budgets and Spend Limits

A budget caps 资产生成 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.

资产生成 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.

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, 资产生成 rejects the request even when the others have room.

Take a team with all four budget scopes in use:

A single request adds its cost to every budget in scope at once. A $1 request from a storefront deployment adds $1 to the project budget and $1 to the team budget, exactly as the diagram shows.

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.

Two requests against that team get different outcomes:

Each budget counts a specific set of authentication types:

• 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.

A default takes effect as soon as you save it. 资产生成 caps every covered resource and lists it with the default's limit and a Default label. Spend shows as $0 until the resource's first request arrives, then starts filling in.

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.

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.

Each refresh period resets at the start of its window in UTC:

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, 资产生成 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": {
    "message": "Project budget exceeded. Current spend: $200.00, limit: $200.00. Please contact your administrator to increase the budget.",
    "type": "quota_for_entity_exceeded"
  }
}

An API key budget:

{
  "error": {
    "message": "Quota limit exceeded for \"api_key_id_<your_key_id>\". Current spend: $10.00, limit: $10.00. Please contact your administrator to increase the quota.",
    "type": "quota_for_entity_exceeded"
  }
}

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 创意脚本 7 or ProviderInternalServerError in the Python beta. Check the quota details before retrying. See 创意脚本 error handling for handling SDK exceptions and streaming errors.

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:

Alerts are informational. Crossing a threshold below 100% never blocks requests.

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.

Writing is more restricted. Besides the Owner role, an Owner can grant a member the 资产生成 Budget Manager permission from the team's member settings; it covers every budget action below without the rest of the Owner role.

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.

The two scopes are independent, and you can use either or both:

• A team budget caps all 资产生成 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.

vercel ai-gateway budgets set team --limit 500 --refresh-period monthly
vercel ai-gateway budgets set project my-project --limit 200 --refresh-period monthly

✓ Set budget      team
  Limit           $500
  Refresh         monthly

vercel ai-gateway budgets list

> Budgets
  scope      name          limit      spent    refresh
  team       acme           $500    $110.00    monthly
  project    storefront     $100    $100.00    monthly

vercel ai-gateway budgets remove team
vercel ai-gateway budgets remove project my-project

✓ Removed         team budget

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.

vercel ai-gateway budgets set project --default --limit 200 --refresh-period monthly

✓ Set default     project
  Limit           $200
  Refresh         monthly
  Applies to      every project without its own budget, including existing ones

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.

Add a budget at the time you create the key:

vercel ai-gateway api-keys create --name my-api-key --limit 10 --refresh-period monthly

your_new_api_key_here
> Success! API key my-api-key (key_123) created [212ms]

vercel ai-gateway api-keys create --name contractor --limit 50 --refresh-period none --expiration 30d

vercel ai-gateway api-keys list

> API keys [387ms]
  id         name          key      budget    spend    refresh    created
  key_123    my-api-key    …1fAj    $10       $1.04    monthly    8/24/2026

vercel ai-gateway api-keys inspect key_123

> API key my-api-key [154ms]
  id              key_123
  name            my-api-key
  key             …1fAj
  purpose         ai-gateway
  project         all projects
  created         8/24/2026, 10:15:03 AM
  last used       8/24/2026, 11:02:47 AM
  expires         never
  created by      your_user_id_here
  budget          $10
  spend           $1.04
  byok spend      $0
  include byok    no
  refresh         monthly
  alerts          none
  active          yes

Give an existing key a budget, or change the one it has, from the dashboard or the CLI.

vercel ai-gateway budgets set api-key my-key --limit 50 --refresh-period weekly

✓ Set budget      api key my-key
  Limit           $50
  Refresh         weekly

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.

vercel ai-gateway budgets remove api-key my-key

✓ Removed         budget for my-key

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.

vercel ai-gateway budgets set api-key --default --limit 50 --refresh-period monthly

✓ Set default     api-key
  Limit           $50
  Refresh         monthly
  Applies to      every API key without its own budget, including existing ones

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.

Only API keys attributed to a member count toward their user budget. OIDC tokens, personal access tokens, and app tokens carry no member attribution, so their spend never counts toward a user budget. See Spend attribution for how a key is attributed to a member or the team.

vercel ai-gateway budgets set user teammate@example.com --limit 100 --refresh-period monthly

✓ Set budget      user teammate
  Limit           $100
  Refresh         monthly

vercel ai-gateway budgets list

> Budgets
  scope    name        limit     spent    refresh
  user     teammate     $100    $12.40    monthly

vercel ai-gateway budgets remove user teammate@example.com

✓ Removed         budget for teammate

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.

vercel ai-gateway budgets set user --default --limit 50 --refresh-period monthly

✓ Set default     user
  Limit           $50
  Refresh         monthly
  Applies to      every team member without their own budget, including existing ones

Budgets limit usage; they do not reserve or purchase capacity. Your team still needs credits or a payment method to make requests.