Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Organization Billing

Update Spending Caps

Update spending cap configuration.

Configure spending limits and alert thresholds to control costs.

Features:

  • Soft Limit (Budget): Triggers alerts but doesn't block API access
  • Hard Cap: Blocks API access when reached. Setting a positive hard_spending_cap arms enforcement automatically; pass hard_cap_enabled: false in the same request to set the cap without enforcing it. Clearing the cap (null/0) disarms enforcement.
  • Alert Thresholds: Customize when to receive spending notifications

Requirements:

  • Admin permission
  • Only applies to organizations with auto-billing enabled

Example:

# Set $100 budget with alerts at 75% and 100%
response = await client.post(
    "/v1/organizations/billing/spending-caps",
    json={
        "monthly_spending_budget": 10000,  # $100 in cents
        "spending_alert_thresholds": [75, 100],
        "spending_alerts_enabled": True,
    }
)

# Enable hard cap at $500
response = await client.post(
    "/v1/organizations/billing/spending-caps",
    json={
        "hard_spending_cap": 50000,  # $500 in cents
        "hard_cap_enabled": True,
    }
)

# Disable all spending limits
response = await client.post(
    "/v1/organizations/billing/spending-caps",
    json={
        "monthly_spending_budget": None,
        "hard_spending_cap": None,
        "hard_cap_enabled": False,
    }
)
post/v1/organizations/billing/spending-caps

Request body

monthly_spending_budgetinteger nullable

Soft spending limit in USD cents. Triggers alerts but doesn't block API access. Set to null to remove budget limit.

spending_alert_thresholdsinteger[] nullable

Percentage thresholds for spending alerts (0-100). When current spending reaches each threshold, an alert is sent.

spending_alerts_enabledboolean nullable

Whether to send spending alerts when thresholds are crossed.

hard_spending_capinteger nullable

Hard spending limit in USD cents. When reached, API access is blocked. Set to null to remove hard cap.

hard_cap_enabledboolean nullable

Whether to enforce the hard spending cap.

Example request

{
  "monthly_spending_budget": 10000,
  "spending_alert_thresholds": [
    50,
    75,
    90,
    100
  ],
  "hard_spending_cap": 50000
}

Response

Successful Response

monthly_spending_budgetinteger nullable

Soft spending limit in USD cents (null = unlimited)

monthly_spending_budget_usdnumber nullable

Soft spending limit in USD

spending_alert_thresholdsinteger[]

Percentage thresholds for spending alerts

spending_alerts_enabledboolean

Whether spending alerts are enabled

spending_alerts_sentinteger[]

Alert thresholds triggered in current billing cycle

hard_spending_capinteger nullable

Hard spending limit in USD cents (null = no hard cap)

hard_spending_cap_usdnumber nullable

Hard spending limit in USD

hard_cap_enabledboolean

Whether hard spending cap is enforced

current_spending_centsinteger required

Current spending in current billing cycle (cents)

current_spending_usdnumber required

Current spending in current billing cycle (USD)

budget_percentage_usednumber nullable

Percentage of budget used (null if no budget set)

Example response

{
  "monthly_spending_budget": 10000,
  "monthly_spending_budget_usd": 100,
  "spending_alert_thresholds": [
    50,
    75,
    90,
    100
  ],
  "spending_alerts_sent": [
    50,
    75
  ],
  "hard_spending_cap": 50000,
  "hard_spending_cap_usd": 500,
  "current_spending_cents": 23450,
  "current_spending_usd": 234.5,
  "budget_percentage_used": 46.9
}