---
title: "Get machine usage."
method: GET
path: "/v1/machines/{id}/usage"
tags: ["machines"]
---

# Get machine usage.

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

## Request

- Base URL: `https://api.smolmachines.com`
- URL: `https://api.smolmachines.com/v1/machines/{id}/usage`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/smolmachines/apis/smolfleet-api/docs/v1/machines/:id/usage/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the machine's metered usage and cost so far this billing period. Requires the `machine:read` scope.

## Path parameters

- `id` string, required

## Response `200`

Usage and cost so far this billing period

- MachineUsageResponse: Per-machine usage + cost for the current billing period ("cost so far").
  - `cost` CostBreakdown, required: Cost breakdown for a usage period (all amounts in integer micros).
    - `amountDueMicros` integer: What the tenant actually owes: `total − discount − credit_applied`.
    - `baseMicros` integer: Per-machine "slot" fee: alive machine-hours × the plan's base rate. Prices the held VM slot (isolation, scheduling, readiness) independent of consumed compute — it is NOT allocated vCPU/RAM. `serde(default)` so older clients/payloads omitting it still deserialize.
    - `cpuMicros` integer, required
    - `creditAppliedMicros` integer: Portion of the free credit actually consumed this period (`min(free_credit, subtotal − discount)`).
    - `diskMicros` integer: Disk gb·hour cost. `serde(default)` so older clients/payloads omitting it still deserialize.
    - `egressMicros` integer: Egress (gb total) cost.
    - `execMicros` integer, required
    - `freeCreditMicros` integer: The plan's recurring free-credit allotment for the period.
    - `memoryMicros` integer, required
    - `monthlyFeeMicros` integer: Flat platform fee charged for this period (0 on usage-only plans).
    - `totalMicros` integer, required: Gross subtotal: sum of all resource line items, before discounts/credits.
    - `volumeDiscountMicros` integer: Graduated volume discount applied to the subtotal (period-level only; always 0 on per-machine breakdowns).
  - `from` string, required: Start of the period (inclusive), RFC3339.
  - `machineId` string, required: The machine this usage is for.
  - `to` string, required: End of the period (now), RFC3339.
  - `usage` UsageResponse, required
    - `consumedFrom` string: Start of the period the consumed metrics actually cover. `totalUptimeSeconds` and `machineCount` are computed over the requested `from`..`to`. The four consumed dimensions cannot be: they come from the tenant's running per-billing-period counters — the same numbers billing charges on — and no per-window consumed history exists to recompute them from. (Deriving them from the window instead reported PROVISIONED figures that ran 177x the actual bill.) So for any window other than the current billing period this differs from `from`, rather than leaving the response looking as though every number shared one time base.
    - `consumedTo` string: End of the period the consumed metrics actually cover. See `consumedFrom`.
    - `cpuHours` number, double, required: The four metered-and-priced dimensions, over `consumedFrom`..`consumedTo` — NOT over `from`..`to`. Exec is intentionally absent: it is metered for the event timeline but priced at $0, so surfacing it as "usage" here would imply a charge that never happens.
    - `diskGbHours` number, double, required
    - `egressGb` number, double, required
    - `from` string, required
    - `machineCount` integer, required
    - `memoryGbHours` number, double, required
    - `tenantId` string, required
    - `to` string, required
    - `totalUptimeSeconds` integer, required

## Other responses

- `401`: Missing or invalid API key
- `403`: Key lacks the required scope
- `404`: Not found
- `429`: Rate limited; retry after the Retry-After header
- `500`: Internal error

## Changes

- **2026-10-16** `bc31fc04a568`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smolmachines/apis/smolfleet-api/changes/v1/machines/:id/usage/get.md)

---

[API](https://skmtc.dev/smolmachines/apis/smolfleet-api.md) - [All operations](https://skmtc.dev/smolmachines/apis/smolfleet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smolmachines/apis/smolfleet-api/revisions/bc31fc04a568?raw)