Docs
⌘K
Account, keys and webhooks ›

Get usage

GET/v1/usage

Running time and list-price cost of your sandboxes, by sandbox, key, day and hour. apiKeyId narrows it to one key or several.

RequestTypeScript
  1. import { Agental } from "agental-sdk";
  3. const agental = new Agental();
  4. const usage = await agental.usage();
Answer200 OK · Usage
  1. {
  2. "since": string,
  3. "until": string,
  4. "seconds": integer,
  5. "listCostMicros": integer,
  6. "stopped": {
  7. "seconds": integer,
  8. "listCostMicros": integer,
  9. },
  10. "snapshots": {
  11. "kept": integer,
  12. "free": integer,
  13. "chargedSeconds": integer,
  14. "listCostMicros": integer,
  15. },
  16. "mail": {
  17. "received": integer,
  18. "sent": integer,
  19. "costMicros": integer,
  20. "sandboxes": object[],
  21. },
  22. "sandboxes": [{
  23. "sandboxId": string,
  24. "name": string | null,
  25. "size": string,
  26. "running": boolean,
  27. "seconds": integer,
  28. "listCostMicros": integer,
  29. … 2 more
  30. }],
  31. "keys": [{
  32. "apiKeyId": string | null,
  33. "name": string | null,
  34. "sandboxes": integer,
  35. "seconds": integer,
  36. "listCostMicros": integer,
  37. }],
  38. … 6 more
  39. }

Running time of the caller's sandboxes and what it comes to at the list price: the total, each sandbox, each API key that made them, each day and each hour.

Query

since
string
Count running time from this moment. An ISO 8601 date and time. e.g. "2026-10-01T00:00:00Z"
until
string
Count running time up to this moment. Now when omitted, and never later than now.
apiKeyId
string
Only the sandboxes these API keys made: one key id, or several separated by commas, at most 100, with console for those made in the console and runs-on for those GitHub Actions jobs ran on. The total, stopped, mail, sandboxes, days and hours are narrowed to them, and snapshots, which are the account's, is zero; keys stays the whole account's. e.g. "key_3f9a1c2b7d4e5f60,console"

Headers

Authorizationrequired
Bearer key
An API key that may make this call.

Returns

200 Running time of the caller's sandboxes and what it comes to at the list price: the total, each sandbox, each API key that made them, each day and each hour. Stopped time, snapshots past the free ones and mail are beside it, apart. Sandboxes deleted since are included. Without since, this month so far in UTC. With apiKeyId, only the sandboxes those keys made.

Usage15 fields
since
string
until
string
seconds
integer
Whole seconds run inside the window, counted by the meter.
More A sandbox that is running is counted up to now.
listCostMicros
integer
What those seconds come to at the list price, in millionths of a US dollar.
More 27000 is $0.027. Not a charge.
stopped
object2 fields
Stopped time, apart from the running time in seconds and listCostMicros.
seconds
integer
Whole seconds stopped inside the window, with the disk kept.
More A sandbox deleted while its snapshots kept its machine counts as stopped until the last of them goes.
listCostMicros
integer
What those seconds come to at the stopped price, 5% of the running one, in millionths of a US dollar.
More Not a charge here: GET /v1/billing says what is.
snapshots
object4 fields
Snapshots past the free ones in the window.
More Zero with apiKeyId, as snapshots are the account's and not a key's.
kept
integer
Snapshots kept at the end of the window, of sandboxes the account has and of ones it deleted.
free
integer
How many of the oldest cost nothing.
chargedSeconds
integer
Seconds of snapshots kept past the free ones: two of them for an hour is 7200.
listCostMicros
integer
What they come to at 2329 an hour each, $1.70 over a month, in millionths of a US dollar.
More Not a charge here: GET /v1/billing says what is.
mail
object4 fields
Mail in the window.
More It is counted by UTC day, so a window takes the whole of every day it touches. Deleting a message, or a sandbox, takes nothing away from it. The total, and a line for each sandbox that had any. With apiKeyId, only those keys' sandboxes' mail.
received
integer
Messages taken for a sandbox.
sent
integer
Messages a sandbox sent.
costMicros
integer
What they come to at 500 a message, in millionths of a US dollar: $0.50 a thousand.
More It is paid from what the plan includes, as machine time is.
sandboxes
object[]5 fields
sandboxId
string
name
stringnull
received
integer
Messages taken for a sandbox.
sent
integer
Messages a sandbox sent.
costMicros
integer
What they come to at 500 a message, in millionths of a US dollar: $0.50 a thousand.
More It is paid from what the plan includes, as machine time is.
sandboxes
object[]8 fields
A line for each sandbox that ran or was stopped in the window, deleted ones too.
sandboxId
string
name
stringnull
size
string
running
boolean
seconds
integer
Whole seconds run inside the window, counted by the meter.
More A sandbox that is running is counted up to now.
listCostMicros
integer
What those seconds come to at the list price, in millionths of a US dollar.
More 27000 is $0.027. Not a charge.
stoppedSeconds
integer
Seconds it was stopped in the window, with its disk kept.
stoppedListCostMicros
integer
What they come to at the stopped price.
keys
object[]5 fields
The same running time, by the API key that made each sandbox.
More Always the whole account's, whatever apiKeyId says.
apiKeyId
stringnull
The API key that made the sandboxes.
More Null is the console.
name
stringnull
The key's name.
More Null for the console, and for a key deleted since.
sandboxes
integer
Sandboxes it made that ran in the window.
seconds
integer
Whole seconds run inside the window, counted by the meter.
More A sandbox that is running is counted up to now.
listCostMicros
integer
What those seconds come to at the list price, in millionths of a US dollar.
More 27000 is $0.027. Not a charge.
members
object[]4 fields
The same running time, by the person who made each sandbox, the most first.
More Always the whole organization's, whatever apiKeyId says. GET /v1/organizations/{id}/members names them.
userId
stringnull
The person who made the sandboxes: in a team, one of its members, or someone who has left it.
More Null for sandboxes made by whoever runs the service.
sandboxes
integer
Sandboxes they made that ran in the window.
seconds
integer
Whole seconds run inside the window, counted by the meter.
More A sandbox that is running is counted up to now.
listCostMicros
integer
What those seconds come to at the list price, in millionths of a US dollar.
More 27000 is $0.027. Not a charge.
days
object[]6 fields
A line for every UTC day the window touches, days nothing ran included: its running time in seconds and listCostMicros, and beside it the day's stopped time, snapshots and mail.
More Added up, the days come to the totals.
day
string
The day in UTC.
seconds
integer
Whole seconds run inside the window, counted by the meter.
More A sandbox that is running is counted up to now.
listCostMicros
integer
What those seconds come to at the list price, in millionths of a US dollar.
More 27000 is $0.027. Not a charge.
stopped
object2 fields
Stopped time, apart from the running time in seconds and listCostMicros.
seconds
integer
Whole seconds stopped inside the window, with the disk kept.
More A sandbox deleted while its snapshots kept its machine counts as stopped until the last of them goes.
listCostMicros
integer
What those seconds come to at the stopped price, 5% of the running one, in millionths of a US dollar.
More Not a charge here: GET /v1/billing says what is.
snapshots
object2 fields
Snapshots past the free ones that day.
More Zero with apiKeyId.
chargedSeconds
integer
Seconds of snapshots kept past the free ones that day.
listCostMicros
integer
What they come to, in millionths of a US dollar.
mail
object3 fields
Mail that day.
received
integer
Messages taken for a sandbox.
sent
integer
Messages a sandbox sent.
costMicros
integer
What they come to at 500 a message, in millionths of a US dollar: $0.50 a thousand.
More It is paid from what the plan includes, as machine time is.
hours
object[]4 fields
A line for each UTC hour in which a sandbox ran, the earliest first, with its running time.
More Hours nothing ran in are left out.
hour
string
The first moment of the hour, in UTC.
sandboxes
integer
How many sandboxes ran in the hour, for any part of it.
seconds
integer
Whole seconds run inside the window, counted by the meter.
More A sandbox that is running is counted up to now.
listCostMicros
integer
What those seconds come to at the list price, in millionths of a US dollar.
More 27000 is $0.027. Not a charge.
currency
usd
cost
null
What was charged.
More Null: nothing is charged here.
billing
not_configured

Errors and other answers

400 since is not before until, or the two are more than 366 days apart.
404 Not found.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Get limitsGet sandbox usage →