---
title: blossom billing:usage
url: "/docs/reference/cli/billing/usage/"
canonical_url: https://docs.blossom88.com/docs/reference/cli/billing/usage/
markdown_url: https://docs.blossom88.com/docs/reference/cli/billing/usage.md
summary: Show billing usage
categories:
- cli
- reference
---

# blossom billing:usage

Show billing usage

## Usage

    blossom billing:usage [--month MONTH] [--period-range PERIOD_RANGE] [--view VIEW] [--page PAGE] [--limit LIMIT] [--workload WORKLOAD]

## Flags

| Flag | Description |
| --- | --- |
| `--month` | Month to show, formatted YYYY-MM |
| `--period-range` | Billing period as start_timestamp,end_timestamp |
| `--view` | Usage view: account, workload, or records |
| `--page` | Usage record page |
| `--limit, -n` | Usage records per page |
| `--workload` | Workload id to filter usage records |

Examples:

    blossom billing:usage
    blossom billing:usage --month 2026-06
    blossom billing:usage --view account
    blossom billing:usage --view workload
    blossom billing:usage --view records
    blossom billing:usage --view records --page 2 --limit 50
    blossom billing:usage --view records --workload service-123
    BLOSSOM_OUTPUT=json blossom billing:usage --month 2026-06 --view records

Shows organization-scoped provisioned CPU and memory from the same append-only ledger as the Web UI
Billing Usage page. Text output begins with the period, estimated Blossom
charge, list price, discount, billing state, and the time through which the
estimate was calculated. It defaults to the Account
summary, then supports workload summaries and one row per durable or accounted
ledger interval. Record rows use readable vCPU-hours and GB-hours; JSON and CSV
also retain the raw meter quantity and unit for exact reconciliation.

Account and workload views also list outbound data transfer per rate group:
accepted Server bytes, the saved regional rate and the estimated charge. A
newer cumulative report replaces the earlier total; unmeasured traffic is
omitted and never estimated. Accepted bytes are charged once at invoice close.

Defaults:

    period: current billing period
    view: account

Use `BLOSSOM_OUTPUT=json` when scripts or AI agents need totals, summaries, and
records together in a structured response. Numeric cost fields are US dollars;
matching `*_display` fields are formatted for people.

Usage records are database_instance-paginated. Use `--page` and `--limit` to move
through them, or `--workload` to view one workload. Account and workload
summaries always cover the complete selected billing period.

Export raw reconciliation data with:

    blossom billing:usage:export --month 2026-06

## Subcommands

- [billing:usage:export](/docs/reference/cli/billing/usage/export/) - Export billing usage CSV