Skip to content

Set the spending cap

Set or remove the account's monthly spending cap. At the cap, hourly pools stop and egress beyond the allowance slows to 5 Mbit/s per pool without further overage charges. Monthly pools keep running. These limits last until the month ends or the cap increases.

Parameters

#
amountstring
Monthly spending cap in dollars, zero or more.
offboolean
Turn off the monthly spending cap.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
The account's monthly spending cap and what counts against it this month.
Show 4 attributesHide attributes
monthstringAlways present
Calendar month (UTC) that spent_micros counts, as YYYY-MM.
spending_cap_microsinteger | nullAlways present
Cap in millionths of a dollar, or null when off.
spent_microsintegerAlways present
What counts against the cap so far this month, in millionths of a dollar: monthly plans' whole month, hourly time and egress overage.
updatedbooleanAlways present
Whether the setting was saved.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • CLI: heaven login with HEAVEN_API_KEY unset. MCP: Heaven sign-in. cURL: HEAVEN_SIGN_IN_KEY from approved device sign-in (POST /v1/auth/create).
  • A key limited to a command list cannot run this command.
  • Set: Stop hourly plans and egress charges once the month's costs reach the chosen amount. Required: amount. Optional: organization.
  • Off: Remove the spending cap. Required: off. Optional: organization.