# Usage

What your sandboxes ran, and what it comes to at the list price.

`GET /v1/usage`

```shell
curl -X GET "https://agental.io/v1/usage?since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $AGENTAL_API_KEY"
```

- `seconds` is running time, counted by the second. `stopped` is stopped time apart, at the stopped price, and `snapshots` the snapshots past the free ones.
- `listCostMicros` is what it comes to at the list price, in millionths of a US dollar: `27000` is $0.027.
- The answer has the total, a line for each sandbox, a line for each API key that made them, a line for each UTC day and a line for each UTC hour in which something ran. Sandboxes deleted since are included.
- A day in `days` has its running time, and beside it the day's `stopped` time, `snapshots` and `mail`: added up, the days come to the totals. An hour in `hours` has its running time and how many `sandboxes` ran in it, for any part of it. Hours nothing ran in are left out.
- `since` and `until` are ISO 8601 times. Without `since`, it is this month so far.
- `apiKeyId` narrows the total, the sandboxes, their mail, the days and the hours to the sandboxes some API keys made: one key id, or several separated by commas, with `console` for those made in the console. `snapshots` are the account's and no key's, so they are zero then. The keys stay the whole account's.
- `mail` counts the messages received and sent in the window, and `costMicros` is what they come to at $0.50 per 1,000 messages, with a line for each sandbox that had any. Mail is counted by UTC day, so a window takes the whole of every day it touches.

```shell
curl -X GET "https://agental.io/v1/usage?apiKeyId=key_3f9a1c2b7d4e5f60,console" \
  -H "Authorization: Bearer $AGENTAL_API_KEY"
```

The console's Usage page draws the same answer for your plan's cycle, the stretch you are charged by: its spend climbing to what it comes to now, with where it ends at this pace on the day the plan renews, and a line where the plan's credits and your top-ups run out. When the pace crosses that line before the plan renews, the page says when, and which top-up covers the rest. Without a plan it counts calendar months. It can also shade every hour of every day by how many sandboxes ran in it, and Made by narrows it to the keys ticked.

`GET /v1/sandboxes/{id}/usage`

One sandbox. Without `since`, its whole life.

`GET /v1/api-keys/{id}/usage`

The sandboxes one API key made.

> **Tip:** These calls measure. They do not charge: `cost` is null. What you are charged, after the plan, is in [billing](https://agental.io/docs/billing).

## Bursts

Every plan has two limits on sandboxes. Both count in small sandboxes: a tiny counts as half, a small as 1, a medium as 2, a large as 4.

- Running: how many sandboxes can be running at the same time. Past it, a new start is refused with `429 running_limit_reached`. Stopped sandboxes do not count, so keep as many as you like.
- Free burst: how many sandboxes you can start in a short space of time without paying anything extra. Start more, faster, and nothing is refused: the starts past it cost a small burst fee.

| Plan, a month | Running | Free burst |
| --- | --- | --- |
| $0 | 20 | 20 |
| $100 | 100 | 100 |
| $500 | 600 | 200 |
| $2,000 | 2,000 | 400 |

The free burst refills on its own. Each start uses some of it, and what was used comes back by half every 15 minutes. So if you start your whole free burst at once, half of it is free again 15 minutes later, and nearly all of it an hour later. Creating, forking, starting, resuming and recovering a sandbox are all starts. When we move a machine between servers, that is not a start. The console's Billing page shows how much of your free burst is left.

## What a burst costs

Only the starts past the free burst cost anything, and the further past it you go, the more each one costs. On any plan, it works out like this:

| You start at once | Each small past the free burst costs | On the $0 plan |
| --- | --- | --- |
| Up to the free burst | Nothing | 20 smalls: nothing |
| 2 times the free burst | about $0.04 | 40 smalls: about $0.80 |
| 3 times the free burst | about $0.08 | 60 smalls: about $3.20 |

- Burst fees are paid from credits like everything else: first the plan's included usage, then your top-ups. `burstMicros` in `GET /v1/billing` is this month's total, part of `usedMicros`.
- Starting the same sandboxes in one go or one at a time costs the same: what counts is how far past the free burst you are.
- The exact formula, in millionths of a US dollar, with the free burst and what is over it in GiB: fee = 20,000 / (2 × free) × (over after² − over before²).

## Capping burst fees

- A monthly budget: an account spends at most $50 a month on burst fees unless it sets another, under Billing in the console, with `PUT /v1/burst/budget` or with `agental burst budget <dollars>`. A start that would go past it is refused with `429 burst_budget_reached`. A budget of 0 means a start never pays a fee: it is refused instead.
- A cap on one start: send the header `Agental-Max-Burst-Fee` (see below) and a start that would cost more is refused.

## Burst headers and refusals

- A create, fork, start, resume or recover takes the header `Agental-Max-Burst-Fee`: the most it may pay in burst fees, in millionths of a US dollar. `0` refuses any fee. Without it, a start pays what the monthly budget allows.
- It answers with the header `Agental-Burst-Fee`: what it paid, in millionths of a US dollar, `0` when it was free.
- A refusal's body has `feeMicros`, what the start would have cost, and `retryAfterSeconds`, how long until it would cost nothing; the `Retry-After` header says the same. Nothing is made or started.

| Code | Why |
| --- | --- |
| `429 running_limit_reached` | The start would take the account past its plan's running count. Stop a sandbox, or move to a larger plan. |
| `429 burst_fee_too_high` | The fee would be more than `Agental-Max-Burst-Fee` allows. |
| `429 burst_budget_reached` | The fee would take this month's burst fees past the budget. |

`GET /v1/burst`

Where your account stands. With `?size=` and `?count=`, `quote` says what starting that many of that size now would cost.

```shell
curl -X GET "https://agental.io/v1/burst?size=small&count=10" \
  -H "Authorization: Bearer $AGENTAL_API_KEY"
```

- `enforced`: whether the account is held to its plan. False: what it starts is only measured, nothing is refused or charged.
- `plan`: the plan it is on, or null. `limitsPlan`: the plan whose limits it has, and `limitsFrom` why: `plan`, `hand` when we gave it a plan's limits, or `none`, measured as the smallest plan.
- `runningUnits` and `freeBurstUnits`: its running count and free burst, in small sandboxes. `capMb` and `freeMb`: the same in megabytes, 4096 each.
- `runningMb`: the memory of its sandboxes running, being made or being started.
- `meterMb`: what the meter reads. `freeNowMb`: what it may start now for nothing, the free burst less the meter and no more than the room under `capMb`. `overMb`: by how much the meter is over the free burst; while it is, every start costs a fee.
- `halfLifeMinutes` and `feeMicrosPerGib`: the meter's half-life and the fee's rate, as in the formula above.
- `mayStart`: whether it may start a sandbox at all now. A plan out of credit may not: `GET /v1/billing` says why. `unpaid`: whether it is on the free plan and has paid for nothing yet, so it runs and starts at most `free.unpaidUnits` small sandboxes at once, as `GET /v1/billing/plans` gives it.
- `spentMicros`: what it spent on burst fees this month. `budgetMicros`: the most it will, `budgetSet` whether the account set it, and `defaultBudgetMicros` the budget otherwise.
- `nextStart`: for each size its plan makes, what one would cost to start now. `quote`: the same for `?size=` and `?count=`, or null. Each has `size`, `count`, `feeMicros`, `freeInSeconds` (0 when free now, null when it never would be, being more than the free burst) and `overRunningCount` (true when it would be refused for the running count).

`PUT /v1/burst/budget`

Sets the monthly budget for burst fees, in millionths of a US dollar. `null` gives it the default again. It answers as `GET /v1/burst` does.

```shell
curl -X PUT https://agental.io/v1/burst/budget \
  -H "Authorization: Bearer $AGENTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"budgetMicros":20000000}'
```

> **Tip:** `GET /v1/tier` still answers in its old shape for older clients, worked out from the bursts. Use `GET /v1/burst`.

---

Every page of these docs as Markdown: [llms.txt](https://agental.io/llms.txt)