Cap what an API key spends
Set spend caps on an API key per hour, day or week, or in total, so tasks that would pass a cap are refused before they cost anything.
An API key spend cap limits what one API key can spend per period or in total. A task whose estimate would take a cap past its amount is refused with ERROR_API_KEY_BUDGET_EXCEEDED and costs nothing. Your balance and your other API keys are not affected, so caps keep one integration, environment or customer from using up the whole balance.
A workspace spend cap counts all keys in that workspace. If the estimate would exceed both a key cap and a workspace cap, the key cap is checked first.
Before you start
Setting or changing a spend cap on a key needs two permissions in the organization, API keys: Edit and Spend limits: Edit, and access to the key's workspace. The owner has all of them. Without Spend limits: Edit, the caps of a key show but are locked, with the note "Changing spend caps needs the Spend limits permission." Permissions lists what each one allows.
Add spend caps to a key
Caps are a setting on the API key, set in the dashboard. No request field sets or overrides them.
- Open the key's workspace from Workspaces, click API keys, then Edit on the key. For a new key, the same field is in the Create key dialog.
- Under Spend cap, click Set limit. Once the key has a cap, the button reads Add limit.
- Enter the amount in USD, then the period: a whole number of hours, days or weeks, or in total for a cap that never resets.
- Click Add limit for each further cap. The counter beside it shows how many of the 5 caps the key uses.
- Click Save changes (or Create key for a new key).
For example, $20 every 1 day, $100 every 2 weeks and $500 in total let the key spend at most $20 per UTC day, $100 per two-week window and $500 in all. Each task is checked against every cap, and refused when it would pass any one of them.
The form marks a cap that breaks one of these rules and lists Fix the highlighted spend caps. under Fix these issues first until you correct it:
- The amount is from $0.01 to $1,000,000, with at most 6 decimal places.
- The period is a whole number of hours, days or weeks, from 1 hour to 90 days.
- Each period has at most one cap, compared in hours:
1 dayand24 hoursare the same period, so the second shows "Another limit already uses this period." - A key has at most one in total cap: a second shows "Only one total limit is allowed."
Check that it works
On the workspace's API keys page, the Spend column of a capped key shows the cap closest to its amount as a bar, for example $4.20 / $20.00 with per day beside it. Hover the bar to see every cap with what it has spent and when it resets. A key without caps shows what it spent in the time range picked for the page, and No API key spend cap under it.
In the key's Edit dialog, each saved cap shows a line such as $4.20 of $20.00 spent · resets in 7 hours, or refuses new tasks when reached for the in total cap.
ERROR_API_KEY_BUDGET_EXCEEDED
A createTask request whose estimate would take a cap on the key past its amount returns:
{
"errorId": 1,
"errorCode": "ERROR_API_KEY_BUDGET_EXCEEDED",
"errorDescription": "This task would exceed a spend budget set on this API key. Wait for its period to reset, or raise the budget in the dashboard (a total budget never resets)."
}solveTask returns the same body with "status": "failed" added. Both endpoints return HTTP 200 for refusals. Branch on errorCode.
The refused task is not created and not charged. There is no taskId, nothing leaves your balance and no cap counts it, on the key or on its workspace. A cheaper task can still pass the same cap, because the check compares each task's own estimate with the room left; a bar at 98% can refuse an expensive task and accept a cheap one.
The response does not say which cap refused the task. Open the API keys page of the key's workspace and hover the key's Spend bar to find the full cap, then apply its fix:
| Cap that is full | Fix |
|---|---|
| A period cap | Wait for the reset time shown on the cap, or raise its amount |
| The in total cap | Raise its amount or remove it: a total cap never resets |
| Any cap | Send the tasks with another API key that has room under its caps, or no caps |
Don't retry the same request in a loop. Until a period cap resets or you change the cap, every retry fails the same way.
How caps count spend
At createTask or solveTask, AnySolver adds the task's estimate to every cap on the key, then to every cap on the key's workspace, before your balance is charged. The estimate is the price of the first provider in the routing order. If adding it would take any cap past its amount, the task is refused and no cap changes. The check and the addition are atomic, so concurrent tasks cannot pass a cap together.
When the task ends, each cap is corrected to what you actually paid for it:
- A refunded failure takes the whole estimate back off.
- A solve that costs less than the estimate takes the difference off.
- A solve that costs more adds the difference, for example after Auto Fallback moves the task to a more expensive provider.
Until a task ends, it counts at its estimate. A key or workspace near its cap refuses new tasks even if some running ones are later refunded.
A task on your own provider key counts what AnySolver charges for it: nothing within the monthly free allowance, the 2% fee past it. What the task costs on your key counts only against the key's own caps, which are reserved per attempt in the same way as these. Spend caps on own keys covers them.
The extra cost of a task that costs more than its estimate is added when the task ends, without a check, because the money is already spent. A cap can therefore end above its amount. The overshoot is at most the sum of those extra costs over the tasks that were running when the cap filled. The next task is then refused.
A request refused with ERROR_ZERO_BALANCE or ERROR_WORKSPACE_BUDGET_EXCEEDED does not count against any cap: AnySolver takes its estimate back off before answering. A refund granted after a manual review (an INCIDENT_REFUND) takes the refunded amount back off every cap the task counted against, on the key and on its workspace: the in total cap, and each period cap in the window the task was created in.
When a period cap resets
Period caps count over fixed windows in UTC, not a rolling window of the last N hours. The windows of one period length run back to back from a fixed start, Monday 5 January 1970 at 00:00 UTC, not from when you add the cap. A period that fits a whole number of times into a week therefore resets every Monday at 00:00 UTC, among other times; a whole number of weeks resets on a Monday. Other lengths reset on changing weekdays.
| Period | Window starts |
|---|---|
1 hour | On every UTC hour |
12 hours | At 00:00 and 12:00 UTC |
1 day | At 00:00 UTC |
2 days | At 00:00 UTC every second day, on varying weekdays |
1 week | On Monday at 00:00 UTC |
2 weeks | On every other Monday at 00:00 UTC |
The dashboard shows the exact reset time of each cap. A task counts toward the window it was created in, even when it ends after that window has reset.
Because windows are fixed, a key can spend a full period cap just before a reset and a full cap again right after it. To bound that, pair a short cap with a longer one, such as $20 every 1 day with $100 every 1 week.
An in total cap has no window and never resets. Once it is full, tasks are refused until you raise its amount or remove it.
Change or remove a cap
Changes apply to the next task. A cap counts only tasks created while it is set, so spend from earlier in the period is not included.
- Changing a cap's amount keeps what it has counted.
- Changing a cap's period counts the new period from what that period has already counted in its current window: $0 unless a cap with that period was set earlier in the window.
- Removing a period cap and adding it back with the same period in the same window resumes its count.
- Adding an in total cap where there is none starts its count from $0, so removing the total cap and adding it back restarts it.
Related
Workspaces
Group an organization's API keys into workspaces, cap what each workspace spends, pick the dashboard default and limit members to some workspaces.
Read your usage and health
What the Overview and Usage pages show about your traffic, which period and scope every number covers, and what each metric means.