---
title: "Upsert AI Gateway budget"
method: PUT
path: "/ai-gateway/budgets"
tags: ["ai-gateway"]
---

# Upsert AI Gateway budget

`PUT /ai-gateway/budgets`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/ai-gateway/budgets`
- Auth: HTTP bearer

Create or update a team-, project-, or user-scope AI Gateway budget.

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `scopeType` 'team' | 'project' | 'user', required
  - `projectId` string: Required when scopeType is "project".
  - `userId` string: Required when scopeType is "user".
  - `limitAmount` number, required: Budget limit in dollars.
  - `refreshPeriod` 'daily' | 'weekly' | 'monthly' | 'none'
  - `includeByokInQuota` boolean: Whether BYOK usage counts toward this budget.
  - `alertThresholds` number[]

## Response `200`

- AiGatewayBudget
  - `active` false | true, required
  - `alertThresholds` number[]
  - `archived` false | true, required
  - `createdAt` number, required
  - `currentByokSpend` number, required
  - `currentSpend` number, required
  - `includeByokInQuota` false | true, required
  - `limitAmount` number, required
  - `name` string
  - `quotaEntityId` string, required
  - `refreshPeriod` 'daily' | 'monthly' | 'none' | 'weekly', required
  - `scopeId` string, required: The native Vercel id of the scoped entity. Team/project ids already carry their prefix, so this equals `quotaEntityId` (`team_…` / `prj_…`); for the api-key scope it is the api key id (the `api_key_id_` prefix stripped).
  - `scopeType` 'api-key' | 'project' | 'team' | 'user', required
  - `source` 'default': Set when the row is inherited from the team's budget default.
  - `updatedAt` number, required

## Other responses

- `400`: One of the provided values in the request body is invalid.
- `401`: The request is not authorized.
- `403`: You do not have permission to access this resource.
- `404`
- `410`
- `500`

## Changes

- **2026-09-30** `6f68095b42b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/api/changes/ai-gateway/budgets/put.md)

---

[API](https://skmtc.dev/vercel/apis/api.md) - [All operations](https://skmtc.dev/vercel/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/api/revisions/4a06e85c2848?raw)