Answers which tier the caller is on, what it allows, and what is left to spend.
Answers which tier the caller is on, what it allows, and what is left to spend. `effectiveAvailable` is the ONLY figure to compare against zero.
GET /v1/billing/tier
| Address | https://api.hanzo.ai/v1/billing/tier |
| Method | GET |
| Operation | get_billing_tier |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Answers which tier the caller is on, what it allows, and what is left to spend.
effectiveAvailable is the ONLY figure to compare against zero. The others are
its parts — prepaid money, granted credits and the daily term are three sources
of one spend, not three balances to add up a second time.
A tier that cannot be READ is an error, never Free. The router in front of the models maps any non-2xx to Free, so answering Free from a question nobody could answer would pin every paying customer to the most restrictive row with nothing anywhere to find.
A named handler, not a closure, so zipdoc can lift this prose into the registry.
Request
GET /v1/billing/tier takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | Tier | ok |
200 body — 20 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
balance | body | TierBalance | — | |
balance.creditsRemaining | body | integer | — | |
balance.currency | body | string | — | |
balance.dailyRemaining | body | integer | — | |
balance.effectiveAvailable | body | integer | — | |
balance.prepaidAvailable | body | integer | — | |
tier | body | TierLimits | — | |
tier.allowedModels | body | string[] | — | |
tier.dailyCreditsCents | body | integer | — | |
tier.displayName | body | string | — | |
tier.maxAgents | body | integer | — | |
tier.name | body | string | — | |
tier.unlimitedAgents | body | boolean | — | UnlimitedAgents reports that MaxAgents 0 means "no ceiling" rather than "no agents" — the reading a bare zero cannot carry. |
user | body | string | — | |
windows | body | Window[] | — | |
windows[].limit | body | integer | — | |
windows[].remaining | body | integer | — | |
windows[].resets | body | string | — | |
windows[].span | body | string | — | |
windows[].used | body | integer | — |
Failure carries the platform error shape — see Errors.
Examples
hanzo billing tierimport { Configuration, BillingApi } from 'hanzoai';
const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getBillingTier();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).get_billing_tier()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.BillingAPI.GetBillingTier(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::get_billing_tier(&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).getBillingTier();curl https://api.hanzo.ai/v1/billing/tier \
-H "Authorization: Bearer $HANZO_API_KEY"Tool commerce, op get_billing_tier — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "commerce",
"arguments": {
"op": "get_billing_tier",
"input": {}
}
}
}'How is this guide?