List allowance

Answers what the CALLER has left of their plan's free-call allowance this period, and the instant the count starts again.

GET /v1/allowance

Allowance → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/allowance`
Method	`GET`
Operation	`get_allowance`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Answers what the CALLER has left of their plan's free-call allowance this period, and the instant the count starts again.

This is the number a product shows beside the composer — "17 of 20 left today" — and the moment to offer a plan is when it reaches zero. It READS: asking does not spend, so a page that polls it costs the caller nothing.

A bounded caller is POOLED: the Free plan is limited usage from one pool every free user shares — the platform's vendor accounts for free models — so the answer says so (pooled) and carries that pool's standing: available, busy or exhausted, and when it refills. The pool is read from the process that spends it and is absent when that process does not answer, never guessed. A paid plan is not pooled and carries no pool: its usage is metered in money.

The subject is the caller's own, resolved from the verified credential, and can never be named in the request — so this is a mirror, not a lookup of someone else. An unauthenticated caller is refused: there is no allowance without someone to hold it.

A named handler, not a closure, so zipdoc can lift this prose into the registry.

Request

GET /v1/allowance takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	allowance.Allowance	ok
`default`	problem-details	refused

200 body — 10 fields.

Field	In	Type	Always	Description
`limit`	body	integer (int64)	—	calls the plan allows per period; 0 = unbounded
`plan`	body	string	—	the tier the limit came from
`pool`	body	allowance.Pool	—
`pool.resets`	body	integer (int64)	—	Resets is when the pool refills, unix seconds: set when it is exhausted, and when it is busy for less than a minute.
`pool.state`	body	string	—	State is "available" (every account takes free requests), "busy" (some account is at its vendor limit, or all are and one is back within a minute) or "exhausted" (none is until Resets).
`pooled`	body	boolean	—	Pooled says the calls counted here are served from the pool every free user shares — the platform's vendor accounts for free models — rather than from the subject's own plan.
`resets`	body	integer (int64)	—	unix seconds; when THAT window starts again
`spent`	body	boolean	—	Spent says the ceiling refuses: on a take, that THIS call was refused and nothing was counted; on a read, that the next call would be.
`used`	body	integer (int64)	—	Used is how many free calls this subject has been admitted in the period ending at Resets — the UTC calendar day.
`window`	body	string	—	Window is which ceiling these numbers describe — "hour" or "day" — because a caller is held to both and only one of them is the answer.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo allowance get

.ts

.py

.go

.rs

.java

import { Configuration, AllowanceApi } from 'hanzoai';

const api = new AllowanceApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAllowance();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AllowanceApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AllowanceApi(client).get_allowance()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AllowanceAPI.GetAllowance(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, allowance_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = allowance_api::get_allowance(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AllowanceApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AllowanceApi(client).getAllowance();

curl https://api.hanzo.ai/v1/allowance \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches allowance through the allowance tool, which names its 1 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_allowances"
         }
       }
     }'

Allowance API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousReplace workflows NextCreate ask