---
title: update-an-ai-gateway-api-key-budget
product: vercel
url: /docs/rest-api/sdk/ai-gateway/update-an-ai-gateway-api-key-budget
canonical_url: "https://vercel.com/docs/rest-api/sdk/ai-gateway/update-an-ai-gateway-api-key-budget"
last_updated: 2026-10-23
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about update-an-ai-gateway-api-key-budget on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Update an AI Gateway API key budget

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

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

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `apiKeyID` | string | Yes | The ID of the API key whose quota should be updated. |


## Request body

Required: No

Content-Type: `application/json`

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

## Example request

```typescript
import { Vercel } from "@vercel/sdk";

const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});

async function run() {
  const result = await vercel.aiGateway.updateApiKeyQuota({
    apiKeyID: "<id>",
  });

  console.log(result);
}

run();
```

## Example response

```json
{
  "apiKey": {
    "id": "5d9f2ebd38ddca62e5d51e9c1704c72530bdc8bfdd41e782a6687c48399e8391",
    "name": "API Key for AI Gateway",
    "partialKey": "t7V",
    "teamId": "team_123a6c5209bc3778245d011443644c8d27dc2c50",
    "purpose": "ai-gateway",
    "projectId": "prj_12HKQaOmR5t5Uy6vdcQsNIiZgHGB",
    "expiresAt": "1632816536002",
    "activeAt": "1632816536002",
    "createdAt": "1632816536002",
    "createdBy": "ZspSRT4ljIEEmMHgoDwKWDei",
    "leakedAt": "1632816536002",
    "leakedUrl": "https://example.com",
    "createdByAppId": "example_id",
    "quota": {
      "quotaEntityId": "example_id",
      "limitAmount": "123",
      "currentSpend": "123",
      "currentByokSpend": "123",
      "includeByokInQuota": "true",
      "refreshPeriod": "string",
      "active": "true",
      "archived": "true",
      "alertThresholds": [],
      "createdAt": "123",
      "updatedAt": "123"
    },
    "metadata": "value"
  },
  "quota": {
    "quotaEntityId": "example_id",
    "limitAmount": "123",
    "currentSpend": "123",
    "currentByokSpend": "123",
    "includeByokInQuota": "true",
    "refreshPeriod": "string",
    "active": "true",
    "archived": "true",
    "alertThresholds": [],
    "createdAt": "123",
    "updatedAt": "123"
  }
}
```

## Responses

### 200: Successfully updated the API key quota.

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "apiKey",
    "quota"
  ],
  "properties": {
    "apiKey": {
      "type": "object",
      "description": "Represents an API key.",
      "required": [
        "id",
        "name",
        "partialKey",
        "teamId",
        "purpose",
        "projectId",
        "expiresAt",
        "activeAt",
        "createdAt",
        "createdBy",
        "leakedAt",
        "leakedUrl",
        "createdByAppId"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The unique identifier of the API key."
        },
        "name": {
          "type": "string",
          "description": "The human-readable name of the API key."
        },
        "partialKey": {
          "type": "string",
          "description": "The last few characters of the API key string, for helping identify the API key."
        },
        "teamId": {
          "type": "string",
          "description": "The ID of the team that the API key grants access to."
        },
        "purpose": {
          "type": "string",
          "description": "The API key's purpose, i.e. what resources it can be used with."
        },
        "projectId": {
          "type": "string",
          "description": "The ID of the project that this API key grants access to.\n\nWhen this is unset, the API key grants access to all projects in the team.",
          "nullable": true
        },
        "expiresAt": {
          "type": "number",
          "description": "Timestamp (in milliseconds) of when the API key expires.",
          "nullable": true
        },
        "activeAt": {
          "type": "number",
          "description": "Timestamp (in milliseconds) of when the API key was most recently used."
        },
        "createdAt": {
          "type": "number",
          "description": "Timestamp (in milliseconds) of when the API key was created."
        },
        "createdBy": {
          "type": "string",
          "description": "The ID of the user who created the API key."
        },
        "leakedAt": {
          "type": "number",
          "description": "Timestamp (in milliseconds) of when the API key was marked as leaked.",
          "nullable": true
        },
        "leakedUrl": {
          "type": "string",
          "description": "URL where the API key was discovered as leaked.",
          "nullable": true
        },
        "createdByAppId": {
          "type": "string",
          "description": "The ID of the app that created the API key, if any",
          "nullable": true
        },
        "quota": {
          "type": "object",
          "description": "AI Gateway quota associated with an API key.",
          "required": [
            "quotaEntityId",
            "limitAmount",
            "currentSpend",
            "currentByokSpend",
            "includeByokInQuota",
            "refreshPeriod",
            "active",
            "archived",
            "createdAt",
            "updatedAt"
          ],
          "properties": {
            "quotaEntityId": {
              "type": "string",
              "description": "The unique identifier for the quota."
            },
            "limitAmount": {
              "type": "number",
              "description": "The quota limit amount."
            },
            "currentSpend": {
              "type": "number",
              "description": "The current amount spent against the quota."
            },
            "currentByokSpend": {
              "type": "number",
              "description": "The current BYOK spend (tracked separately)."
            },
            "includeByokInQuota": {
              "type": "boolean",
              "description": "Whether BYOK (Bring Your Own Key) spend counts against the quota."
            },
            "refreshPeriod": {
              "description": "How often the quota refreshes."
            },
            "active": {
              "type": "boolean",
              "description": "Whether the quota is currently active."
            },
            "archived": {
              "type": "boolean",
              "description": "Whether the quota has been archived."
            },
            "alertThresholds": {
              "type": "array",
              "description": "Spend percentages (a subset of [50, 75, 100]) at which to send a spend alert. Empty or undefined disables alerts."
            },
            "createdAt": {
              "type": "number",
              "description": "Timestamp (in milliseconds) of when the quota was created."
            },
            "updatedAt": {
              "type": "number",
              "description": "Timestamp (in milliseconds) of when the quota was last updated."
            }
          }
        },
        "metadata": {
          "type": "object",
          "description": "Generic metadata attached to the API key.\n\nThe 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": {
      "type": "object",
      "description": "AI Gateway quota associated with an API key.",
      "required": [
        "quotaEntityId",
        "limitAmount",
        "currentSpend",
        "currentByokSpend",
        "includeByokInQuota",
        "refreshPeriod",
        "active",
        "archived",
        "createdAt",
        "updatedAt"
      ],
      "properties": {
        "quotaEntityId": {
          "type": "string",
          "description": "The unique identifier for the quota."
        },
        "limitAmount": {
          "type": "number",
          "description": "The quota limit amount."
        },
        "currentSpend": {
          "type": "number",
          "description": "The current amount spent against the quota."
        },
        "currentByokSpend": {
          "type": "number",
          "description": "The current BYOK spend (tracked separately)."
        },
        "includeByokInQuota": {
          "type": "boolean",
          "description": "Whether BYOK (Bring Your Own Key) spend counts against the quota."
        },
        "refreshPeriod": {
          "description": "How often the quota refreshes.",
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "string"
            }
          ]
        },
        "active": {
          "type": "boolean",
          "description": "Whether the quota is currently active."
        },
        "archived": {
          "type": "boolean",
          "description": "Whether the quota has been archived."
        },
        "alertThresholds": {
          "type": "array",
          "description": "Spend percentages (a subset of [50, 75, 100]) at which to send a spend alert. Empty or undefined disables alerts.",
          "items": {
            "type": "number"
          }
        },
        "createdAt": {
          "type": "number",
          "description": "Timestamp (in milliseconds) of when the quota was created."
        },
        "updatedAt": {
          "type": "number",
          "description": "Timestamp (in milliseconds) of when the quota was last updated."
        }
      }
    }
  }
}
```

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

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
```

### 403: You do not have permission to access this resource.

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
```

### 404: No description

### 410: No description

### 429: No description

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "name",
        "message",
        "limit"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "limit": {
          "type": "number"
        }
      }
    }
  }
}
```

### 500: No description

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
```

---

## Related

- [ai-gateway endpoints](/docs/rest-api#ai-gateway)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://vercel.com/openapi.json) (machine-readable, all endpoints)

---

[View full sitemap](/docs/sitemap)


If you find anything wrong or missing or can't find something, submit feedback by reading https://vercel.com/feedback.md to improve Vercel.