docs(cli): document usage commands (#1408)

* docs(usage-api): add Usage API reference under the Admin API section

Vendors the Usage API OpenAPI spec (GET /v1/usage/summary,
POST /v1/usage/time-series) into src/openapi/usage-api and wires it into the
Admin API nav section as "Usage API Endpoints", mirroring how the Admin API
("Apps API") endpoints are surfaced.

The spec is vendored locally for now because usage-api.alchemy.com is not yet
serving its /openapi.yaml publicly; once it is, this can switch to a
content/remote-specs.json entry (like admin-api) for auto-sync.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(usage-api): use admin-api.alchemy.com as the server

The Usage API is path-routed (`/v1/usage*`) through the Apps API ALB at
admin-api.alchemy.com (see terraform aws_alb_listener_rule.admin_api_usage),
not served directly at usage-api.alchemy.com. Match the public host (and the
sibling admin-api spec's server) so the reference shows the correct base URL.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(usage-api): use remote spec instead of vendored copy

Per the sync-docs-as-code pattern, register the Usage API spec as a remote
entry (served at https://admin-api.alchemy.com/v1/usage/openapi.json) and
remove the vendored src/openapi/usage-api/ copy. content/docs.yml already
references api-name: usage-api; the remote entry now supplies it.

Blocked: merge only after the dashboard change serving the spec at that URL
deploys (OMGWINNING/dashboard#8050) — CI lints the live URL.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(cli): document usage commands

Add a Usage (alpha) section to the Alchemy CLI reference covering
`alchemy usage summary` and `alchemy usage timeseries`, including the
time-series flag table for date ranges, granularity, filters, and
group-by.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(cli): drop alpha framing from usage section

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: lohnim

content/docs.yml

@@ -125,6 +125,9 @@ navigation:
               - api: Admin API Endpoints
                 api-name: admin-api
                 flattened: true
+              - api: Usage API Endpoints
+                api-name: usage-api
+                flattened: true
           - section: Activity Log
             hidden: true
             contents:

content/remote-specs.json

@@ -3,6 +3,10 @@
     "name": "admin-api",
     "url": "https://admin-api.alchemy.com/openapi.yaml"
   },
+  {
+    "name": "usage-api",
+    "url": "https://admin-api.alchemy.com/v1/usage/openapi.json"
+  },
   {
     "name": "wallet-api",
     "url": "https://txe-api-specs.docs.alchemy.com/wallet/openrpc.yaml",

content/tutorials/build-with-ai/alchemy-cli.mdx

@@ -269,6 +269,40 @@ The CLI uses your browser login automatically for Admin API commands. It also ca
 | `alchemy app select [id]` | Select an app to use as the default for subsequent commands |
 | `alchemy app chains` | List Admin API chain identifiers (e.g. `ETH_MAINNET`) for app configuration |
 
+### Usage
+
+The `usage` commands use your browser login automatically, like the Admin API commands above. Track and visualize your account's API usage with summaries and time-series reports.
+
+| Command | Description |
+|---|---|
+| `alchemy usage summary` | Get an account usage summary |
+| `alchemy usage timeseries` | Get account usage time-series data. Alias: `time-series`. |
+
+```bash
+alchemy --json usage summary
+alchemy usage timeseries --start-date 2026-06-01 --granularity day
+alchemy usage timeseries --start-date 2026-06-01 --group-by network --metrics usd
+```
+
+`timeseries` accepts a date or time range, optional filters, and a single group-by dimension.
+
+| Flag | Description |
+|---|---|
+| `--start-date <date>` | Start date (`YYYY-MM-DD`). Required unless `--start-time` is set. |
+| `--end-date <date>` | End date (`YYYY-MM-DD`). Defaults to now. |
+| `--start-time <datetime>` | Start time as an ISO datetime with a timezone |
+| `--end-time <datetime>` | End time as an ISO datetime with a timezone |
+| `--granularity <granularity>` | `hour` or `day` (default `day`) |
+| `--products <products>` | Comma-separated billing product names |
+| `--metrics <metrics>` | Comma-separated metrics: `amount`, `usd` |
+| `--app-ids <ids>` | Filter by app IDs (comma-separated) |
+| `--networks <networks>` | Filter by networks (comma-separated), e.g. `eth-mainnet,base-mainnet` |
+| `--methods <methods>` | Filter by methods (comma-separated), e.g. `eth_getLogs` |
+| `--request-types <types>` | Filter by request types (comma-separated): `http`, `websocket`, `webhook`, `grpc` |
+| `--group-by <dimension>` | Group by one dimension: `requestType`, `app`, `network`, `method` |
+
+Filters are optional and combined with AND. `--group-by` accepts at most one dimension.
+
 ### Auth and config
 
 | Command | Description |