# Billing history and usage reports

Source: https://docs.oiy.ai/docs/billing-history

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 [#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 [#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 [#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 [#read-the-amounts-correctly]

Amounts are integer **micro-USD**: 1 USD = 1,000,000 micro-USD.

* `compute` and `storage` totals express charged amounts as positive numbers.
* `credits` sums positive postings, including positive adjustments.
* `adjustments` is the signed sum of adjustment entries and overlaps with credits when adjustments are positive.
* `net` is the signed total change across matching entries. Do not add `credits` and `adjustments` to 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 [#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 [#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 [#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](/docs/api/billing). These reports do not initiate a payment, allocate compute, or change resource rates.