List Budgets

GET /budgets

List Budgets

List every budget in the organization, across all scopes, each with its current-period spend state. Budgets whose spend is not tracked as a single total (team_member) return a zero-seeded state: the limit applies to each member of the team separately.

Parameters

Responses

• 200: OK

• data (array, required): Every budget in the organization.

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

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

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

• data[].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.

• data[].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.

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

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

• data[].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.

• data[].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.

• data[].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.

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

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

• data[].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

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

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

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

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

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

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

• 401: Missing or invalid bearer.

• 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.

cURL

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