Get Budget

GET /budgets/{budget_id}

Get Budget

Return one budget together with its current-period spend state. The state starts as a zero seed at creation and updates as spend is aggregated.

Parameters

• budget_id (path, string, required): Budget ID.

Responses

• 200: OK

• budget (object, required): A spending cap on one target. Amounts are integer USD cents.

• budget.id (string, required): Budget ID.

• budget.org_id (string, required): Organization that owns this budget.

• budget.scope (string, required): What a budget's spend counts. org caps the whole organization. environment caps one environment. api_key caps one caller API key and provider_key one upstream credential. team is a pool shared by every caller API key bound to the team. member is organization-wide for one member: all caller API keys bound to that member, in any team. team_member gives every member of one team an individual allowance of the same size, counting only their spend through keys bound to both that team and that member.

• budget.scope_ref (string, required): ID of the target the budget applies to, matching scope: an environment ID, caller API key ID, provider key ID, team ID, or member ID. team_member budgets reference a team ID. For org budgets this holds the organization's internal ID, which differs from the organization identifier used elsewhere in this API. Fixed at creation.

• budget.display_name (string, required): Human-readable budget name.

• budget.limit_cents (integer, required): Spending limit in USD cents.

• budget.period (string, required): Calendar window the limit applies to, in UTC: day resets at 00:00, week on Monday 00:00, month on the 1st at 00:00.

• budget.hard_stop (boolean, required): Whether the gateway rejects matching traffic with 429 budget_exceeded once the period's spend reaches the limit. When false the budget only reports the over-limit state.

• budget.alert_thresholds (array, optional): Percent-of-limit points at which a budget_threshold notification fires once per period, delivered to the organization's enabled notification channels. null means the default ([80]). Values above 100 fire under either enforcement mode and flag overspend: hard_stop rejects new requests once the control plane observes spend at the limit, but it does not cap the cost of requests already admitted, so a hard-stopped budget can settle above 100.

• budget.created_at (string, required): Time when the budget was created.

• budget.updated_at (string, required): Time when the budget was last updated.

• state (object, required): Current-period spend. Seeded at zero when the budget is created. For team_member budgets it stays at the zero seed: spend is tracked per member of the team, not as one total.

• allOf variant 1

• state.period_start (string, required): Start of the period the totals cover.

• state.spent_cents (integer, required): Spend accumulated in the period, in USD cents.

• state.crossed_75_at (string, required): Time the period's spend first reached 75% of the limit. null while below the threshold.

• state.crossed_90_at (string, required): Time the period's spend first reached 90% of the limit. null while below the threshold.

• state.crossed_100_at (string, required): Time the period's spend first reached the limit. null while below the limit.

• state.updated_at (string, required): Time the totals were last refreshed.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to GET /budgets/{budget_id}, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to GET /budgets/{budget_id}, response 400 above.

cURL

curl -X GET '$AISIX_CP/budgets/{budget_id}' -H 'Authorization: Bearer $AISIX_TOKEN'