Docs / Guides
Projects and budgets
Group keys into projects, give a project a daily or monthly budget, and archive projects you no longer use.
Last updated
What a project is
A project is a group of API keys. Use projects to separate apps, environments or teams, for example production and staging.
- Every key belongs to exactly one project.
- Every account starts with a project named Default. A key created without a project goes there.
- Your balance is one per account. A project limits spending; it is not a separate wallet.
Create a project
Open Projects in the dashboard to create, rename or archive a project. When you create a key in Keys, choose its project.
Usage, Requests and the CSV export can all be filtered by project. The totals of all projects add up to the account total.
Budgets
Each project can have a daily budget, a monthly budget, or both. Both are optional; an empty budget means no budget. A budget works like a limit on a key, but it counts the spending of every key in the project.
Periods use UTC: a day starts at 00:00 UTC, and a month starts on its first day at 00:00 UTC.
When a project reaches its budget, every key in that project gets HTTP 429 project_budget_exceeded until the next period starts or you raise the budget. Other projects in the same account keep working.
{"error": {"message": "This project reached its monthly budget. Raise the budget or wait until 2026-11-01T00:00:00Z.", "type": "rate_limit_error", "param": null, "code": "project_budget_exceeded"}}
Requests already running
Budgets are checked when a request starts. A request that is already running when the budget is reached, including a long stream, finishes and is charged in full. The next request is rejected. Spending can therefore go a little past the budget.
Budget and key limits together
A request must pass every check. In order:
| # | Check | Result when it fails |
|---|---|---|
| 1 | The key's project is not archived | 403 project_archived |
| 2 | The key's daily or monthly limit | 429 key_limit_exceeded |
| 3 | The project's daily or monthly budget | 429 project_budget_exceeded |
| 4 | Balance available for the model | 402 insufficient_balance |
A project budget does not add money. If the balance runs out first, requests return 402 even when the budget has room. See Balance.
Archive a project
Archiving a project:
- stops every key in it within seconds; they return HTTP 403
project_archived - blocks new keys in that project
{"error": {"message": "This key belongs to an archived project. Restore the project to use it again.", "type": "permission_error", "param": null, "code": "project_archived"}}
When the project is restored, its keys work again. The Default project cannot be archived.
Read projects from code
GET /v1/organization/projects returns every project with its budgets and what it spent today and this month. It needs a management key. See Usage API.