Skip to main content
There is no spend cap on this surface today. You cannot set a dollar limit or a minute limit that suspends a lease or refuses the next one. There is one alert, and it is only an alert. If your deployment has been given a level to watch for, we email you once when your next invoice reaches eighty percent of it and once when it reaches the whole of it. Nothing is paused, refused or slowed down at either point, and the alert is off unless that level has been set, which it is not by default. The figure it watches is the next invoice total, which for a subscription already includes the plan fee, so a level set at or below the plan price would fire every period before you had used anything. That is worth stating first, because the alternative is a reader who assumes a cap is there. What follows is what you can actually use instead. The honest answer to “how do I avoid a surprise bill” is a handful of existing limits rather than one switch.

​
What bounds your bill today

​
The lease lifetime is a ceiling you already have

A lease expires on its own after 10 minutes, and it can be renewed, but no lease may live longer than 60 minutes from when it was acquired. On a per minute device that hour is the most a single forgotten lease can cost: Then it stops. Walking away for an afternoon costs at most one hour, not the afternoon. A client that keeps renewing is a client that is still running; one that crashed stops renewing, and the device frees itself within 10 minutes. Nothing pauses the clock for idleness, so this expiry is doing the job you might otherwise expect an idle timeout to do. See Metering units.
One forgotten lease is bounded. A loop that keeps taking the device is not. If you write a retry that re-acquires on failure, give it a stopping condition and a ceiling on attempts. The same goes for a loop that releases the device and then goes on acting on it: a gesture on a device your organization no longer holds takes it again, and each new lease starts its own fresh hour.

​
A run carries its own budget

start_run takes two limits and both of them are real ceilings, not hints:
  • maxSteps, the number of frames the run may consume. The default is 50 per run, and your value can only lower it.
  • deadlineMs, an absolute wall clock deadline, also capped by the deployment and by your lease’s own expiry, whichever comes first.
A run that reaches either limit is refused its next frame rather than billed further. See Agent tier.

​
Monthly mode removes the variable

A monthly device has no meter, no allowance and no overage: run it all month and the invoice reads the same. If predictability matters more than the arithmetic, that is the mode that gives it to you outright. See Billing modes.

​
Reading what you have spent

Two reads, both on the hosted control plane, both needing only devices:read:
  • GET /v1/usage returns this billing period’s settled usage per device: measured active time with corrections already applied, how many leases it came from, and the minutes already reported to billing.
  • GET /v1/receipts enumerates what your org has actually done, newest first, with keyset paging.
Use get_receipt when you hold an idempotencyKey and need that one outcome back. Use GET /v1/receipts when the question is what happened at all. Two things to read carefully before you build a budget alarm on this. Only settled leases appear in usage, so a lease you are holding right now is not in those numbers: it is an account of what has finished, not a live meter. And reportedMinutes is absent until reporting has happened, which is not the same as zero. Usage for your org is also shown in the hosted product, if your org has an account there.

​
What is on the way

A hard cap that suspends billing when a limit is reached is a roadmap item, not a shipped feature. Usage settles slightly behind real time, so a cap has to decide what to do about a lease that is already open when the limit is crossed, and that is not decided yet. The limits above are the whole of what bounds your bill today.