Usage

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

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.

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.

One sandbox. Without since, its whole life.

The sandboxes one API key made.

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.

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:

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

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

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

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.

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

The full machine-readable reference is OpenAPI 3.1. Every page as Markdown, for an agent: llms.txt. Questions: [email protected]