---
title: "Update an AI Gateway API key budget"
method: PATCH
path: "/api-keys/{apiKeyID}/quota"
tags: ["ai-gateway"]
---

# Update an AI Gateway API key budget

`PATCH /api-keys/{apiKeyID}/quota`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/api-keys/{apiKeyID}/quota`
- Auth: HTTP bearer

Set, change, or remove the AI Gateway budget on an API key. Creates the budget if the key does not have one.

## Path parameters

- `apiKeyID` string, required: The ID of the API key whose quota should be updated.

## Request body

- object
  - `limitAmount` number: The quota limit amount. Required if the quota does not yet exist.
  - `includeByokInQuota` boolean: Whether BYOK (Bring Your Own Key) usage counts against the quota.
  - `refreshPeriod` 'daily' | 'weekly' | 'monthly' | 'none': How often the quota refreshes.
  - `active` boolean: Whether the quota is currently active.
  - `archived` boolean: Set to true to archive (soft-delete) the quota. The api key itself is unaffected.
  - `alertThresholds` number[]: Spend percentages (a subset of [50, 75, 100]) at which to send a spend alert. Pass an empty array to disable alerts.

## Response `200`

Successfully updated the API key quota.

- object
  - `apiKey` APIKey, required: Represents an API key.
    - `id` string, required: The unique identifier of the API key.
    - `name` string, required: The human-readable name of the API key.
    - `partialKey` string, required: The last few characters of the API key string, for helping identify the API key.
    - `teamId` string, required: The ID of the team that the API key grants access to.
    - `purpose` string, required: The API key's purpose, i.e. what resources it can be used with.
    - `projectId` string, nullable, required: The ID of the project that this API key grants access to. When this is unset, the API key grants access to all projects in the team.
    - `expiresAt` number, nullable, required: Timestamp (in milliseconds) of when the API key expires.
    - `activeAt` number, required: Timestamp (in milliseconds) of when the API key was most recently used.
    - `createdAt` number, required: Timestamp (in milliseconds) of when the API key was created.
    - `createdBy` string, required: The ID of the user who created the API key.
    - `leakedAt` number, nullable, required: Timestamp (in milliseconds) of when the API key was marked as leaked.
    - `leakedUrl` string, nullable, required: URL where the API key was discovered as leaked.
    - `createdByAppId` string, nullable, required: The ID of the app that created the API key, if any
    - `quota` APIKeyQuota: AI Gateway quota associated with an API key.
      - `quotaEntityId` string, required: The unique identifier for the quota.
      - `limitAmount` number, required: The quota limit amount.
      - `currentSpend` number, required: The current amount spent against the quota.
      - `currentByokSpend` number, required: The current BYOK spend (tracked separately).
      - `includeByokInQuota` boolean, required: Whether BYOK (Bring Your Own Key) spend counts against the quota.
      - `refreshPeriod` union, required: How often the quota refreshes.
        - string
        - string
        - string
        - string
      - `active` boolean, required: Whether the quota is currently active.
      - `archived` boolean, required: Whether the quota has been archived.
      - `alertThresholds` number[]: Spend percentages (a subset of [50, 75, 100]) at which to send a spend alert. Empty or undefined disables alerts.
      - `createdAt` number, required: Timestamp (in milliseconds) of when the quota was created.
      - `updatedAt` number, required: Timestamp (in milliseconds) of when the quota was last updated.
    - `metadata` object: Generic metadata attached to the API key. The accepted shape depends on the key's `purpose` and is validated when the key is created. For `ai-gateway` keys this carries `environment` and `spendAttribution`.
  - `quota` APIKeyQuota, required: AI Gateway quota associated with an API key.
    - `quotaEntityId` string, required: The unique identifier for the quota.
    - `limitAmount` number, required: The quota limit amount.
    - `currentSpend` number, required: The current amount spent against the quota.
    - `currentByokSpend` number, required: The current BYOK spend (tracked separately).
    - `includeByokInQuota` boolean, required: Whether BYOK (Bring Your Own Key) spend counts against the quota.
    - `refreshPeriod` union, required: How often the quota refreshes.
      - string
      - string
      - string
      - string
    - `active` boolean, required: Whether the quota is currently active.
    - `archived` boolean, required: Whether the quota has been archived.
    - `alertThresholds` number[]: Spend percentages (a subset of [50, 75, 100]) at which to send a spend alert. Empty or undefined disables alerts.
    - `createdAt` number, required: Timestamp (in milliseconds) of when the quota was created.
    - `updatedAt` number, required: Timestamp (in milliseconds) of when the quota was last updated.

## Other responses

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

## Changes

- **2026-10-23** `99958249a01e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/api/changes/api-keys/:apiKeyID/quota/patch.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)