Budgets
List budgets
Returns all budgets, optionally filtered by workspace.
Needs a token with viewBudgets; a workspace token lists its own workspace only.
query Parameters
workspaceIdpageThe page to return, counted from 1. A page below 1 reads page 1; one past the last returns no items.
limitItems per page, from 1 to 100. A larger value is clamped to 100, a smaller one to 1.
List budgets › Responses
Success
Create budget
Creates a budget over a workspace, a segment or a saved cost report: a start date, a cadence of N days, weeks, months or years, and one amount for every period or an amount per period, with optional alert thresholds on the spend so far or on the forecast for the period's end, and notification channels. A usage budget (measure usage) counts one usage unit on a saved cost report's rows instead of money, and takes no forecast threshold; a report holds at most one cost and one usage budget.
Needs a token with createBudget on the workspace.
Headers
Idempotency-KeyA unique value, at most 255 printable ASCII characters, such as a UUID, that makes retrying this create safe. A retry with the same key and the same request within 24 hours answers the first response again, marked Idempotent-Replayed: true, and creates nothing; the same key with another request answers 422 idempotency_key_reused. A key is kept only for a create that succeeded. Without it, every request creates.
Create budget › Request Body
workspaceId^wsp_[A-Za-z0-9_-]{2… · requirednamecurrency^[A-Z]{3}$ · requiredmeasureusageUnitstartDateintervalCountintervalUnitamount^-?[0-9]+(\.[0-9]{1,…segmentIdappIdsCreate budget › Responses
Created
id^bud_[A-Za-z0-9_-]{2… · requirednamecurrency^[A-Z]{3}$ · requiredmeasurestartDateintervalCountintervalUnitstatusstatespendAvailabilitycreatedAtamount^-?[0-9]+(\.[0-9]{1,…usageUnitcurrentSpend^-?[0-9]+(\.[0-9]{1,…budgetedToDate^-?[0-9]+(\.[0-9]{1,…projectedSpend^-?[0-9]+(\.[0-9]{1,…percentUsedhistoryFloorupdatedAtGet budget
Returns a specific budget with current spend.
Needs a token with viewBudgets on the workspace.
path Parameters
budgetId^bud_[A-Za-z0-9_-]{2… · requiredGet budget › Responses
Success
id^bud_[A-Za-z0-9_-]{2… · requirednamecurrency^[A-Z]{3}$ · requiredmeasurestartDateintervalCountintervalUnitstatusstatespendAvailabilitycreatedAtamount^-?[0-9]+(\.[0-9]{1,…usageUnitcurrentSpend^-?[0-9]+(\.[0-9]{1,…budgetedToDate^-?[0-9]+(\.[0-9]{1,…projectedSpend^-?[0-9]+(\.[0-9]{1,…percentUsedhistoryFloorupdatedAtUpdate budget
Updates the name, the amounts, the scope (a segment, a cost report or the whole workspace), a usage budget's unit, the alert thresholds or the notification channels of a budget in place; the start date, cadence and measure are fixed once created, and a usage budget keeps a cost report. A field left out keeps its value; clearSegment and clearCostReport return the budget to the whole workspace. Alerts replace the thresholds: one kept at the same percent and basis keeps whether it fired this period.
Needs a token with updateBudget on the workspace.
path Parameters
budgetId^bud_[A-Za-z0-9_-]{2… · requiredHeaders
If-MatchApplies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.
Update budget › Request Body
nameamount^-?[0-9]+(\.[0-9]{1,…segmentIdclearSegmentclearCostReportappIdsusageUnitUpdate budget › Responses
Success
id^bud_[A-Za-z0-9_-]{2… · requirednamecurrency^[A-Z]{3}$ · requiredmeasurestartDateintervalCountintervalUnitstatusstatespendAvailabilitycreatedAtamount^-?[0-9]+(\.[0-9]{1,…usageUnitcurrentSpend^-?[0-9]+(\.[0-9]{1,…budgetedToDate^-?[0-9]+(\.[0-9]{1,…projectedSpend^-?[0-9]+(\.[0-9]{1,…percentUsedhistoryFloorupdatedAtDelete budget
Deletes a budget and its alert configuration.
Needs a token with deleteBudget on the workspace.
path Parameters
budgetId^bud_[A-Za-z0-9_-]{2… · requiredHeaders
If-MatchApplies the write only while the resource still has this ETag, and answers 412 precondition_failed otherwise. Without it, the last write wins.
Delete budget › Responses
No Content