PUT/api/orgs/{org_id}/budgets

Set a monthly budget

Creates or replaces the cap for one scope. Provisioning key only; a key may set identity and key scopes only (422 otherwise), never on the default identity (403), and may replace only rows its own key authored (403). The response meters the current month for a recurring budget.

Authentication: Bearer API key in the Authorization header

Path parameters

  • org_idstringrequired

    Your organization id (uuid). GET /api/whoami returns it.

Request body

  • periodstringrequired

    YYYY-MM, or * for a recurring budget enforced every month against that month's spend.

  • scope_kindenumrequired

    API keys may set identity and key only.

    "team""identity""key""model""pool""deployment"
  • limit_nano_usdintegerrequired

    Integer nano-USD (1 USD = 1,000,000,000). 0 refuses every request under the scope; remove a cap with DELETE.

  • api_key_idstring | null
  • identity_idstring | null
  • alias_idstring | null
  • pool_idstring | null
  • deployment_idstring | null

Responses

  • 200

    The budget.

    Response
    • budget_idstringrequired
    • periodstringrequired

      YYYY-MM, or * for recurring.

    • scope_kindenumrequired
      "team""identity""key""model""pool""deployment"
    • api_key_idstring | nullrequired
    • identity_idstring | nullrequired
    • alias_idstring | nullrequired
    • pool_idstring | nullrequired
    • deployment_idstring | nullrequired
    • limit_nano_usdintegerrequired

      The cap, integer nano-USD. 0 is a hard zero cap.

    • reserved_nano_usdintegerrequired

      In flight, integer nano-USD.

    • settled_nano_usdintegerrequired

      Spent this month, integer nano-USD.

    • remaining_nano_usdintegerrequired

      Integer nano-USD.

    • created_by_kindenumrequired
      "session""api_key"
    • created_by_api_key_idstring | nullrequired

      The authoring key; a key may change only its own rows.

  • 401

    Missing, unknown or revoked API key.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 403

    Not a provisioning key, the default identity, or a row set by an admin or another key.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 404

    Unknown organization, identity, key or model.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 422

    Bad period or scope, wrong identifiers for the scope, a scope a key may not set, or body validation.

Request

curl -X PUT https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/budgets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "period": "*",
  "scope_kind": "identity",
  "identity_id": "acme-support",
  "limit_nano_usd": 50000000000
}'

Response

{
  "budget_id": "b7e1c0d2-5a4f-4c39-8e16-2d9f0a7b3c51",
  "period": "*",
  "scope_kind": "identity",
  "api_key_id": null,
  "identity_id": "acme-support",
  "alias_id": null,
  "pool_id": null,
  "deployment_id": null,
  "limit_nano_usd": 50000000000,
  "reserved_nano_usd": 120000000,
  "settled_nano_usd": 18400000000,
  "remaining_nano_usd": 31480000000,
  "created_by_kind": "api_key",
  "created_by_api_key_id": "6b1d2f4e-3c8a-4f0e-9a21-7e5c0d9b4a33"
}

https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/budgets