Usage and cost

Objective

This is the only way to see cost before an invoice exists. There is no cost explorer, no budget alert, no per-resource breakdown and no tag allocation.

GET /v1/usage

Session required. Returns what your project is running, and what it has been rated so far this month.

Response

{
  "machines": [
    {
      "id": "…",
      "name": "web",
      "status": "ACTIVE",
      "flavor": "cd-standard-2-4",
      "addresses": ["10.200.0.7"],
      "created": "2026-09-01T09:14:02Z"
    }
  ],
  "month_to_date": 12.4,
  "since": "2026-09-01T00:00:00.000Z"
}

Field	Meaning
`machines[].id`	The machine’s identifier in the control API
`machines[].name`
`machines[].status`	`ACTIVE`, `SHUTOFF`, `BUILD`, `ERROR` — the control-API status, not the EC2 state name
`machines[].flavor`	Our shape name
`machines[].addresses`	Every address on the machine, private and public, flattened into one list
`machines[].created`
`month_to_date`	Rated amount since `since`, in the billing currency
`since`	Midnight UTC on the first of the current month

Neither number is computed by this service. What is running comes from the compute service; what it has cost comes from the rating service. This endpoint joins them and nothing more.

The two-hour lag

[!warning]

An hour is rated about two hours after it ends. The newest hours are not in month_to_date yet.

A machine you launched twenty minutes ago contributes nothing to this figure. Neither does one you launched two hours ago, most likely.

This is the single most important thing to know about the number. Consequences:

Do not build an alert on a threshold and expect it to fire promptly. By the time spend appears, it is at least two hours old.
Do not use it to verify a shutdown worked. Check machines for that — that half is live.
Do not reconcile against it mid-hour. Compare complete days.
Month boundaries are UTC, not your local midnight. A month-to-date figure read at 00:30 local time may still be counting the previous month depending on where you are.

The machines list has no such lag. When you need “is it running”, read that. When you need “what has it cost”, accept that you are reading the recent past.

Polling

Rating happens hourly, so poll hourly at most. A tighter loop returns the same number and spends round trips to get it.

If you want a live view of what is running, the machines half is safe to poll more often — but even then, prefer the compute API’s own describe call, which is what it is for.

`month_to_date` is a total, not a breakdown

One number for the whole project. It does not tell you which machine, which shape, or which hour.

For that, query the rating service directly with your cloud token — it returns the rated rows behind the total: which resource, which shape, which hour, which rate. That is the evidence to quote if a bill looks wrong. See Metering and invoicing.

What is not in the number

Only compute is rated. Storage, snapshots, egress and addresses contribute nothing to month_to_date because nothing rates them yet.

That is a gap, not a discount. A cost model built on today’s month_to_date will understate a future bill. See How prices are set.

Opening a machine’s console

POST /v1/machines/{id}/console
→ { "url": "https://…" }

Returns a browser console for one machine — the equivalent of a Console button. Three properties worth knowing:

Single-use and time-limited. A fresh URL is minted on every call rather than stored, so do not cache one and do not paste one into a ticket.
Ownership is checked first. The machine is read and its project compared with yours before a console is opened; another project’s machine returns a 404. This check is the only thing separating customers here, because the service that performs it is privileged.
It works before the network does — which is the day you need it. See Web console and VNC.

Example

const { machines, month_to_date, since } = await call("/v1/usage");

console.log(`${machines.length} running, €${month_to_date.toFixed(2)} since ${since}`);
for (const m of machines) {
  console.log(m.name, m.flavor, m.status, m.addresses.join(", "));
}

Render since beside the figure. A cost with no period attached invites the reader to assume it means today.