Budgets

Budgets hold the money your organization and its projects spend on AI usage, and the per-user spend limits that apply inside them. These endpoints let you read the budgets you administer, see what each member has spent against their limit, and set per-user limits in bulk.

Every organization has one organization budget. When project budgets are turned on, each project can also have a project budget that draws from the organization budget. Funding, renewal, overage behavior, and whether member limits are on are changed in the admin UI; the API reads them and sets per-member limits.

All paths below are relative to your instance's base URL (https://<your-domain>.nomic.ai/api/v0). See the overview for authentication details.

Scopes​

The broad developer scope implies developer:budgets:write, which in turn implies developer:budgets:read.

Scopes only let a key call these endpoints; access to each budget still follows your role. Organization admins administer the organization budget and every project budget. A project admin administers that project's budget. A budget you do not administer is reported as 404.

Wherever a path takes a budget {id}, you can pass organization in place of a UUID to address the organization budget.

List budgets​

GET /budgets

List the budgets the caller administers: the organization budget first, then project budgets by name. All budgets fit in one page, so nextCursor is always null.

Scope: developer:budgets:read · Rate limit: Standard (300 req / min)

Query parameters​

Response​

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "name": "Acme",
      "parentId": null,
      "scope": { "type": "organization", "projectBudgetsEnabled": true },
      "funding": {
        "amountCents": 5000000,
        "spentCents": 1234500,
        "remainingCents": 3765500,
        "renewal": null
      },
      "onExhausted": "block",
      "memberLimits": {
        "enabled": true,
        "defaultCents": 20000,
        "period": "monthly",
        "resetsAt": "2026-11-01T00:00:00.000Z"
      }
    },
    {
      "id": "019abc12-3456-7890-abcd-ef1234567891",
      "name": "Downtown Office Tower",
      "parentId": "019abc12-3456-7890-abcd-ef1234567890",
      "scope": {
        "type": "project",
        "projectId": "019c587e-3456-7890-abcd-ef1234567890"
      },
      "funding": {
        "amountCents": 100000,
        "spentCents": 42000,
        "remainingCents": 58000,
        "renewal": { "cadence": "monthly", "amountCents": 100000 }
      },
      "onExhausted": "use_parent",
      "memberLimits": {
        "enabled": false,
        "defaultCents": null,
        "period": null,
        "resetsAt": null
      }
    }
  ],
  "nextCursor": null,
  "totalCount": 2
}

Errors​

Example​

curl "https://<your-domain>.nomic.ai/api/v0/budgets?scope=project" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

Get a budget​

GET /budgets/{id}

Fetch a single budget. Pass organization as the ID for the organization budget, which holds the organization-wide per-user limits.

Scope: developer:budgets:read · Rate limit: Standard (300 req / min)

Path parameters​

Response​

Returns 200 OK with the budget under data, in the same shape as an item of List budgets.

Errors​

Example​

curl "https://<your-domain>.nomic.ai/api/v0/budgets/organization" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

List budget members​

GET /budgets/{id}/members

List each member's own limit, the limit that applies to them, and their spend in the budget's current window, ordered by email. The organization budget covers every user in the organization; a project budget covers the project's members.

Scope: developer:budgets:read · Rate limit: Standard (300 req / min)

Path parameters​

Query parameters​

Response​

{
  "data": [
    {
      "id": "019abc12-3456-7890-abcd-ef1234567890",
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "limitCents": 50000,
      "effectiveLimitCents": 50000,
      "spentCents": 12340,
      "status": "within_limit"
    },
    {
      "id": "019abc12-3456-7890-abcd-ef1234567891",
      "email": "bob@example.com",
      "name": "Bob Lee",
      "limitCents": null,
      "effectiveLimitCents": 20000,
      "spentCents": 20000,
      "status": "limit_reached"
    }
  ],
  "nextCursor": null,
  "totalCount": 2
}

Errors​

Example​

curl "https://<your-domain>.nomic.ai/api/v0/budgets/organization/members?limit=100" \
  -H "Authorization: Bearer $NOMIC_API_KEY"

Set budget member limits​

POST /budgets/{id}/members

Set or clear per-user limits in one batch of 1–100 changes, applied atomically: nothing is written unless every entry is valid. A limitCents of null clears the member's own limit so the budget's default applies. Sending the same batch twice changes nothing.

Member limits must be turned on for the budget, and every user must already be one of the budget's members; identify each by user ID or email. Changing limits on the organization budget requires the key owner to be an organization admin.

Scope: developer:budgets:write · Rate limit: Write (60 req / min)

Path parameters​

Request body​

Response​

Returns 200 OK with the changed members after the batch, ordered by email, in the same shape as List budget members (without pagination fields).

Errors​

Example​

Give Bob a $250 limit and put Carol back on the budget default:

curl -X POST "https://<your-domain>.nomic.ai/api/v0/budgets/organization/members" \
  -H "Authorization: Bearer $NOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      { "user": "bob@example.com", "limitCents": 25000 },
      { "user": "carol@example.com", "limitCents": null }
    ]
  }'