Budget Spend Status

View as Markdown

The calling user's live spend against the blocking thresholds of a single budget.

Get the calling user's spend status for a budgetGET /api/2.1/{name=accounts/*/budget-spend-statuses/*}List the calling user's budget spend statusesGET /api/2.1/{parent=accounts/*}/budget-spend-statuses

BudgetSpendStatus object

The calling user's live spend against the blocking thresholds of a single budget.

namestringBetaIDImmutable

The resource name of this budget spend status, of the form accounts/{account_id}/budget-spend-statuses/{budget_id}.

alert_spend_statusesarray of objectBeta

The calling user's spend against each blocking threshold on this budget, one entry per scope type and time period. A blocking threshold is a threshold that, once reached, blocks further requests through Unity Gateway.

Show child attributesHide child attributes

scope_typestringBeta

Whether the threshold is evaluated per individual user (ALERT_CONFIGURATION_SCOPE_TYPE_PER_USER) or on the shared spend across all users (ALERT_CONFIGURATION_SCOPE_TYPE_SHARED).

Values:

• ALERT_CONFIGURATION_SCOPE_TYPE_SHARED
• ALERT_CONFIGURATION_SCOPE_TYPE_PER_USER

time_periodstringBeta

The time window the threshold applies to, for example MONTH.

Values:

• MONTH

spendstringBeta

The calling user's live spend against this threshold, in USD at list price. Returns "0" if the caller has no usage. Omitted for shared thresholds, where only percent_consumed is returned.

thresholdstringBeta

The calling user's effective threshold, in USD at list price. The effective threshold is the actual threshold amount that applies to the user, after adjusting for any user or group overrides. Omitted for shared thresholds, where only percent_consumed is returned.

percent_consumedstringBeta

Percentage of the threshold consumed, as a decimal string rounded down to one decimal place (for example, "68.4" means 68.4%). May exceed 100 when spend is over the threshold. Returns "0.0" if there's no spend, and is omitted if the threshold is $0. For shared thresholds, this is the only value returned; the absolute spend and threshold dollar amounts are withheld.

View as Markdown

The BudgetSpendStatus object

{
  "name": "string",
  "alert_spend_statuses": [
    {
      "scope_type": "ALERT_CONFIGURATION_SCOPE_TYPE_SHARED",
      "time_period": "MONTH",
      "spend": "string",
      "threshold": "string",
      "percent_consumed": "string"
    }
  ]
}

Get the calling user's spend status for a budget Beta

GET /api/2.1/{name=accounts/*/budget-spend-statuses/*}

Get the calling user's live spend against the blocking thresholds of a single Unity Gateway budget. Any account user can call this for their own spend. Spend is reported in USD at list price and is near-real-time, so it may differ slightly from billing data. Returns NOT_FOUND if the budget doesn't exist or has no blocking thresholds.

API scopes: billing

Parameters

namestringRequiredpath

The resource name of the budget spend status to read, of the form accounts/{account_id}/budget-spend-statuses/{budget_id}. A budget_id that isn't a valid UUID fails with INVALID_PARAMETER_VALUE.

Response

Returns the BudgetSpendStatus object.

View as Markdown

Response

{
  "name": "string",
  "alert_spend_statuses": [
    {
      "scope_type": "ALERT_CONFIGURATION_SCOPE_TYPE_SHARED",
      "time_period": "MONTH",
      "spend": "string",
      "threshold": "string",
      "percent_consumed": "string"
    }
  ]
}

List the calling user's budget spend statuses Beta

GET /api/2.1/{parent=accounts/*}/budget-spend-statuses

List the calling user's live spend against the blocking thresholds across the account's Unity Gateway budgets. Any account user can call this for their own spend. Spend is reported in USD at list price and is near-real-time, so it may differ slightly from billing data. By default, returns every budget in the account that has a blocking threshold. Use filter to narrow results by workspace.

API scopes: billing

Parameters

parentstringRequiredpath

The parent account whose budget spend statuses to list, of the form accounts/{account_id}.

page_tokenstringquery

A page token from a previous ListBudgetSpendStatuses response, used to fetch the next page. Requests the first page if absent. All other request parameters except page_size must match the request that returned the token; otherwise the request fails with INVALID_PARAMETER_VALUE.

page_sizeint32query

The maximum number of spend statuses to return per page. If unspecified or 0, at most 100 are returned. The maximum value is 100; values above 100 are coerced to 100. Negative values fail with INVALID_PARAMETER_VALUE. The server may return fewer results than requested, including zero, even when more pages remain; page until next_page_token is absent.

filterstringquery

A filter expression that narrows the returned budgets by workspace. Only workspace_id is supported, in lower case with numeric workspace IDs, for example workspace_id = 123 or workspace_id IN (123, 456). Matches budgets that apply to any of the listed workspaces, including budgets that apply to all workspaces. Any other expression, such as an empty IN () list, fails with INVALID_PARAMETER_VALUE. If empty, returns every budget in the account that has a blocking threshold.

Response

Returns a list of BudgetSpendStatus objects.

View as Markdown

Response

{
  "budget_spend_statuses": [
    {
      "name": "string",
      "alert_spend_statuses": [
        {}
      ]
    }
  ],
  "next_page_token": "string"
}