Money
Balance, then the usage that moved it.
Balance, then the usage that moved it.
Neither takes an org: both derive the tenant server-side from the JWT owner claim, so a key can only read its own money. Both ids are cloud's now — /v1/billing is among the routes where the binary's own woven document replaced a hand-written spec, so the prose is the handler's.
An example CAN ask for a window again: /v1/billing/usage takes start and end. It briefly did not — the merge was replacing the whole authored operation with cloud's undescribed one, and this note said to stop asking. Both are restored, along with the response schema, so an SDK reads a typed body rather than decoding by hand. See LLM.md, "An empty field from the winner must not delete a populated one".
Prepaid credit balance
GET /v1/billing/balance · reference →
The org's prepaid credit balance in USD cents — the same wallet the gateway debits.
| Parameter | In | Required | Description |
|---|---|---|---|
currency | query | — | Optional currency filter (default usd) |
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, BillingApi } from 'hanzoai';
const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.cloudGetV1BillingBalance();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BillingApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BillingApi(client).cloud_get_v1_billing_balance()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.BillingAPI.CloudGetV1BillingBalance(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, billing_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = billing_api::cloud_get_v1_billing_balance(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BillingApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new BillingApi(client).cloudGetV1BillingBalance();curl https://api.hanzo.ai/v1/billing/balance \
-H "Authorization: Bearer $HANZO_API_KEY"The MCP door does not expose this operation as a tool. It answers tools/list at https://api.hanzo.ai/v1/mcp with the ones it does.
Per-request usage ledger
GET /v1/billing/usage · reference →
The raw per-request billing ledger (one row per billed call) for the caller's own org.
| Parameter | In | Required | Description |
|---|---|---|---|
start | query | — | Optional server-side window start |
end | query | — | Optional server-side window end |
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, BillingApi } from 'hanzoai';
const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.cloudGetV1BillingUsage();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BillingApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BillingApi(client).cloud_get_v1_billing_usage()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.BillingAPI.CloudGetV1BillingUsage(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, billing_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = billing_api::cloud_get_v1_billing_usage(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BillingApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new BillingApi(client).cloudGetV1BillingUsage();curl https://api.hanzo.ai/v1/billing/usage \
-H "Authorization: Bearer $HANZO_API_KEY"The MCP door does not expose this operation as a tool. It answers tools/list at https://api.hanzo.ai/v1/mcp with the ones it does.
Every command, call and tool above is generated from the same OpenAPI document that generates the SDKs themselves — the four surfaces are projections of one doc comment, so they cannot disagree.
How is this guide?