Set a spending ceiling for a period

Create a budget, choose its period and what it covers, read how much of it is left, and change or archive it.

4 min read

A budget is a ceiling on what may be spent in a period. Every hold a model call takes is checked against the budgets that cover it, and a call that does not fit is refused before the provider is asked. This page is about the budgets page of the console; How budget reservations work explains the hold itself.

Where the budgets are

Open Budgets. The page lists the budgets of the project chosen in the header and the budgets of the whole organization. Customer accounts live in their own section, Customers, in the side menu.

Every role reads the budgets. Creating, changing and archiving a budget need management:write: in the console the roles Owner and Admin have it — Organizations, projects and roles. The audit log records each of these changes.

Create a budget

1. Start a new budget

Press Create.

2. Name it

The name is optional and is what the list shows. Without a name the list shows the period and what the budget covers.

3. Choose the period

Under Period choose Daily, Weekly, Monthly or All time. A budget of a day, a week or a month starts again with the next one, and the row says when. A budget of All time never starts again.

4. Choose what it covers

Under Applies to choose This project or Whole organization. The second choice is offered only to a member who reaches every project. A budget of the whole organization counts the spend of every project in it.

5. Set the limit

Fill in Limit, an amount in the currency of the organization with up to eight decimal places: 3000 or 12.50.

6. Narrow it to one operation

To cap only the calls of one operation, open Advanced and fill in the operation code. Leave it empty for a budget of every call.

7. Create the budget

Press Create budget. The next hold is checked against it.

The period, what the budget covers and its operation code cannot be changed later: the spend counted under them would not follow. Create another budget instead.

Read the list

The bar of a row fills with what is still available, beside the limit.
The dot of a row is green while less than 80 % of the limit is used, amber from 80 %, and red when the budget is used up. What is held counts as used, like what is captured.
Per operation and Concurrent holds are budgets of two more kinds, created through the API. The first refuses a single hold larger than its limit, the second counts the holds that are open at once — How budget reservations work.

A call that does not fit a budget is refused with budget_exceeded. A call made under a flow is checked against the same budgets, so a refusal can end the execution or lead it down another branch.

Change, archive or restore a budget

Press a row to open the budget. Captured, On hold and Available show how the limit is used in the current period.

Change the name or the Limit and press Save. A new limit counts from the next hold. A limit below what the period has already used is accepted, and then no new hold fits until the period starts again or the limit is raised.
Archive stops the budget from taking part in new holds, after a confirmation. Holds already taken are still settled.
The archived budgets are folded at the foot of the list. Restore in a row brings the budget back.

A budget of the whole organization is changed only by a caller who reaches every project. An API key acts in its own project, so such a change through the API is refused with project_access_restricted.

Be told before a budget runs out

Slen sends the webhook event budget.threshold_reached when a hold brings the use of a budget to 50 % and to 80 % of its limit, and budget.exceeded when it reaches the whole limit. Each level is announced at most once a period, and a hold that passes two levels at once announces only the higher one. Budgets of the kinds Per operation and Concurrent holds send no such events.
An alert rule of the type Budget threshold watches a share you choose — Alerts.

Where to go next

How budget reservations work — what a hold is, and how it is settled.
Policies — refuse or limit a request by its own conditions.
Alerts — be told when a budget nears its limit.
Audit log — who created, changed or archived a budget.
Budgets — the same budgets over the API, the kinds the console does not create included.
Budget Check — refuse a call of a flow before any money is held.