> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blacksmith.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage and cost reporting

> Pull your Blacksmith usage and cost data programmatically for billing and cost reporting workflows

The Blacksmith CLI is the programmatic way to pull your organization's usage and cost data: billable minutes, estimated spend, and storage costs, broken down by day, repository, workflow, job, or runner type. Every command outputs JSON by default, so you can pipe results into `jq`, spreadsheets, dashboards, or your internal cost reporting and chargeback workflows without scraping the dashboard.

For scripts and CI, authenticate with an [organization token](/blacksmith-cli/overview#token-types) instead of a personal login.

## `blacksmith usage`

Billing-oriented Actions usage for the authenticated organization: jobs, billable minutes, billing minutes, runtime minutes, estimated cost, daily totals, and requested breakdowns.

```bash theme={"system"}
blacksmith usage --since 30d --breakdown-by runner_type,repo --format table
```

| Flag                                                   | Description                                                                    |
| :----------------------------------------------------- | :----------------------------------------------------------------------------- |
| `--since`                                              | Relative time range: `24h`, `7d`, `30d`, `90d`. Defaults to `30d`.             |
| `--start-time`, `--end-time`                           | Absolute RFC3339 time range.                                                   |
| `--breakdown-by`                                       | CSV subset of `day`, `runner_type`, `repo`, `workflow`, `job`, `workflow_job`. |
| `--repo`, `--workflow`, `--job-name`, `--runner-label` | Filters.                                                                       |

### `blacksmith usage storage`

Sticky disk storage usage for a time range: current/peak/average GB, GB-hours, and estimated cost from the hourly storage billing ledger.

```bash theme={"system"}
blacksmith usage storage --since 30d --breakdown-by repo,type
```

## `blacksmith runners catalog`

Lists every Blacksmith runner SKU as a deterministic table of metadata: label, vCPUs, memory, architecture, OS, and cost per minute.

```bash theme={"system"}
blacksmith runners catalog --format table
```