Billing history and usage reports
Explore complete ledger windows, resource charges, pagination, and page exports.
The current preview source provides a complete-window billing summary and cursor-paginated ledger. These reads use the Oiy account ledger, not a supplier invoice. Availability requires the corresponding control-plane deployment.
Choose a UTC window
Select an inclusive date range of 1–90 UTC calendar days, ending no later than today. Query an earlier window to read older history; the window limit does not erase older entries.
The console provides date presets and custom dates. The HTTP endpoints require explicit from and to. The CLI, Python, and MCP clients default to the latest 30-day summary when dates are omitted.
Summary and history serve different purposes
| View | What it includes |
|---|---|
| Summary | Every matching ledger row, complete daily buckets, and aggregate totals |
| Resource ranking | Up to 20 groups, with resourcesTruncated indicating additional groups |
| Ledger | One page of matching postings with a continuation cursor |
| Account snapshot | Only the latest 100 ledger entries; not the full history interface |
Ranking truncation does not truncate summary totals. A ledger page is not a full statement or an invoice.
Filter by the resource you mean
kind can be compute, storage, topup, or adjustment. Select one serviceId to filter compute charges, or one volumeId to filter storage charges. The two resource filters are mutually exclusive.
A service filter cannot be combined with kind: "storage", and a volume filter cannot be combined with kind: "compute". Storage attribution follows the volume, even if its service attachment later changes.
Read the amounts correctly
Amounts are integer micro-USD: 1 USD = 1,000,000 micro-USD.
computeandstoragetotals express charged amounts as positive numbers.creditssums positive postings, including positive adjustments.adjustmentsis the signed sum of adjustment entries and overlaps with credits when adjustments are positive.netis the signed total change across matching entries. Do not addcreditsandadjustmentsto reconstruct it.
Daily buckets use posting dates. Delayed metering can post a charge after its underlying usage. These charts are not a reconstruction of the exact time a workload ran.
Paginate without changing the query
The ledger returns entries and nextCursor. Repeat the original dates and filters, and pass nextCursor as cursor. Stop when nextCursor is null.
The HTTP API accepts 1–100 entries per page, defaulting to 50. MCP intentionally caps its response at 50 entries and defaults to 30. A cursor fixes which insertions belong to the result set, so refresh without a cursor to include new postings.
Open hourly rows can change
Repeated metering within a resource's UTC hour can update an existing row. Its amount, last-posted timestamp, and recorded balance can change while the hour remains open. Ledger responses explicitly report amountsMayUpdate: true.
The row's balanceMicros is the balance at its latest posting, not a running balance across the page you are viewing. Pagination is not an immutable financial snapshot. As with normal account reads, existing meters accrue through the current time before reporting.
Export the visible page
The console's Export page action exports only the currently displayed ledger page, with exact micro-USD values and safely escaped CSV text. It is not presented as an invoice or a complete account statement.
For exact endpoints and client examples, see the Billing API. These reports do not initiate a payment, allocate compute, or change resource rates.