---
title: "List AI Gateway budgets"
method: GET
path: "/ai-gateway/budgets/list"
tags: ["ai-gateway"]
---

# List AI Gateway budgets

`GET /ai-gateway/budgets/list`

## Request

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

List the team's AI Gateway budgets (team/project/user scopes, plus default-covered api-key spend) as a flat list, optionally filtered by scope. Without `limit` or `cursor`, returns every budget. With either, returns one page ordered by `quotaEntityId` plus `nextCursor` (null on the last page) and `defaultCoveredCounts`. Paging still reads the full merge server-side: the gateway meter list it joins has no cursor.

## Query parameters

- `scopeType` 'team' | 'project' | 'user' | 'api-key': Restrict the list to a single budget scope.
- `includeDefaultCovered` 'true' | 'false': Whether to include rows inherited from a budget default (`source: "default"`). Defaults to true.
- `limit` integer: Maximum number of budgets to return (capped at 200). Enables pagination.
- `cursor` string: Opaque cursor returned by a prior call as nextCursor.
- `teamId` string
- `slug` string

## Response `200`

- AiGatewayBudgetList
  - `budgets` AiGatewayBudget[], required
    - `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
  - `defaultCoveredCounts` object: Paged requests only: `source: 'default'` rows per scope type across the whole `scopeType`-filtered list, independent of the page and of `includeDefaultCovered`.
    - `api-key` number, required
    - `project` number, required
    - `team` number, required
    - `user` number, required
  - `nextCursor` string, nullable: Paged requests only (`limit` or `cursor` set): pass as `cursor` to read the next page; null on the last page.

## Other responses

- `400`: 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`
- `500`

## Changes

- **2026-10-15** `8939e3983223`: 5 info
  - added the new optional `query` request parameter `cursor`
  - added the new optional `query` request parameter `includeDefaultCovered`
  - added the new optional `query` request parameter `limit`
  - added the optional property `defaultCoveredCounts` to the response with the `200` status
  - …1 more
- **2026-09-30** `6f68095b42b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vercel/apis/api/changes/ai-gateway/budgets/list/get.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)