Budgets & Spending Caps

Get a project's budget status

Caps, spend this month and the current mode, taking both the account cap and the project cap into account — the stricter one wins.

Optional query param: fresh=true to skip the 15-second cache.

{
    "data": {
      "project_id": "PROJECT_ID",
      "period": "2026-10",
      "mode": "normal",
      "limiting_scope": null,
      "base_mode_pct": 10,
      "account": {
        "cap_atomic_at": 200000000,
        "spend_atomic_at": 48200000,
        "remaining_atomic_at": 151800000,
        "used_pct": 24.1,
        "mode": "normal"
      },
      "project": {
        "cap_atomic_at": 50000000,
        "spend_atomic_at": 12500000,
        "remaining_atomic_at": 37500000,
        "used_pct": 25,
        "mode": "normal"
      }
    }
  }

project is null when the project has no cap of its own; limiting_scope names the cap (account or project) that set the mode.

Set a project's monthly cap

Needs a write role. Send only what you want to change; monthly_cap_atomic_at: null removes the project cap. Returns the updated status.

{
    "monthly_cap_atomic_at": 50000000,
    "base_mode_enabled": true,
    "base_mode_pct": 10
  }

# Cap this project at 50,000 tokens a month
  curl -X PUT https://platform.endlessai.com/api/v1/projects/PROJECT_ID/budget \
    -H "X-Api-Key: YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "monthly_cap_atomic_at": 50000000 }'

  # Check where the project stands
  curl -s "https://platform.endlessai.com/api/v1/projects/PROJECT_ID/budget" \
    -H "X-Api-Key: YOUR_KEY" | jq '.data.mode'

import requests

  headers = {"X-Api-Key": API_KEY}

  requests.put(
      f"{BASE}/projects/{PROJECT_ID}/budget",
      headers=headers,
      json={"monthly_cap_atomic_at": 50_000_000},  # 50,000 tokens
  )

  status = requests.get(
      f"{BASE}/projects/{PROJECT_ID}/budget", headers=headers
  ).json()["data"]
  project = status["project"]
  print(status["mode"], project["spend_atomic_at"] / 1000, "tokens used")

await fetch(`${BASE}/projects/${PROJECT_ID}/budget`, {
    method: "PUT",
    headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ monthly_cap_atomic_at: 50000000 }) // 50,000 tokens
  });

  const res = await fetch(`${BASE}/projects/${PROJECT_ID}/budget`, {
    headers: { "X-Api-Key": API_KEY }
  });
  const { data } = await res.json();
  console.log(data.mode);

Get the account budget

Org admin, with a user token. The account cap, spend this month, and auto-reload settings for your active organization.

{
    "data": {
      "account_id": "ORG_ID",
      "period": "2026-10",
      "monthly_cap_atomic_at": 200000000,
      "spend_this_period_atomic_at": 48200000,
      "base_mode_enabled": true,
      "base_mode_pct": 10,
      "auto_reload": {
        "enabled": true,
        "threshold_atomic_at": 10000000,
        "amount_atomic_at": 25000000,
        "ceiling_atomic_at": 100000000,
        "max_per_period": 3,
        "used_this_period": 1,
        "used_amount_atomic_at": 25000000,
        "has_payment_method": true
      },
      "payment_method": { "saved": true, "label": "visa •••• 4242", "known": true }
    }
  }

spend_this_period_atomic_at is null when spend could not be read — not zero. payment_method.known: false means the saved card could not be checked right now.

Update the account budget

Org admin, with a user token. Send only what you want to change; monthly_cap_atomic_at: null removes the account cap.

{
    "monthly_cap_atomic_at": 200000000,
    "base_mode_pct": 10,
    "auto_reload": {
      "enabled": true,
      "threshold_atomic_at": 10000000,
      "amount_atomic_at": 25000000,
      "ceiling_atomic_at": 100000000
    }
  }

Auto-reload tops up your balance from your saved card when it drops below threshold_atomic_at. The reload amount must be at least the threshold, and the monthly ceiling at least one reload amount — otherwise 400.

List auto-reload history

Org admin. Newest first, every attempt including failed and skipped ones. Query param: limit (default 12).

{
    "data": {
      "reloads": [
        {
          "id": "RELOAD_ID",
          "period": "2026-10",
          "amount_atomic_at": 25000000,
          "status": "succeeded",
          "error": null,
          "created_at": "2026-10-06T03:10:00.000Z"
        }
      ]
    }
  }