List limits

Reads the caller's plan usage: for each class of model the plan includes, the share used of the billing period and of its short window, who pays for the next request, and whether the caller is in limited mode and why; the share used of the session and the day; and the ways on.

GET /v1/ai/limits

AI → · All API references → · Get started →

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

Request

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

Response

Status	Body	Meaning
`200`	aiLimits	ok
`default`	problem-details	refused

200 body — 39 fields.

Field	In	Type	Always	Description
`actions`	body	aiAction[]	—	Actions are the ways on: upgrade, add prepaid credit.
`actions[].kind`	body	string	—
`actions[].label`	body	string	—
`actions[].plan`	body	string	—
`actions[].url`	body	string	—
`classes`	body	object	—	Classes are premium (third-party frontier models) and ours (Hanzo's), each present when the plan includes it.
`classes.*`	body	aiClass	—
`classes.*.paying`	body	string	—	Paying is plan, prepaid, credits, or none.
`classes.*.percent`	body	integer (int64)	—
`classes.*.resets_at`	body	string	—
`classes.*.state`	body	string	—	State is ok, near, or limited when the class is used up and nothing else pays.
`classes.*.unbounded`	body	boolean	—	Unbounded says the plan includes all of this class's use: there is no share to use up, and Percent is 0.
`classes.*.window`	body	aiWindow	—
`classes.*.window.percent`	body	integer (int64)	—	Percent is the share used, 0 to 100, rounded up to the next five so any use shows.
`classes.*.window.resets_at`	body	string	—	ResetsAt is when the window starts again (RFC3339), null for a session that is not running: it starts at the next request.
`classes.*.window.state`	body	string	—	State is ok, near (four fifths used) or limited (used up).
`day`	body	aiWindow	—
`day.percent`	body	integer (int64)	—	Percent is the share used, 0 to 100, rounded up to the next five so any use shows.
`day.resets_at`	body	string	—	ResetsAt is when the window starts again (RFC3339), null for a session that is not running: it starts at the next request.
`day.state`	body	string	—	State is ok, near (four fifths used) or limited (used up).
`limited`	body	aiLimited	—
`limited.classes`	body	string[]	—
`limited.message`	body	string	—
`limited.reason`	body	string	—	Reason is plan_allowance_used.
`paused`	body	aiPaused[]	—	Paused are the models whose share of the plan is used for now: each is answered by its fallback in chat until its share resets.
`paused[].fallback`	body	string	—	Fallback is the Hanzo model that answers a conversation in its place.
`paused[].model`	body	string	—	Model is the model id, or a pattern ending in `*` naming a family of them.
`paused[].resets_at`	body	string	—	ResetsAt is when its share resets (RFC3339).
`pays`	body	object	—	Pays is who pays for the next priced request of each class, on any plan or none: plan (its included usage), prepaid (funds the caller added), credits (granted credit, where it pays for the class) or none (nothing does: a request of the class is refused 402 insufficient_balance until funds are added, the `topup` action).
`pays.*`	body	string	—
`period_end`	body	string	—
`period_start`	body	string	—	PeriodStart and PeriodEnd bound the month the plan's usage renews over (RFC3339): the billing period, or one month of a yearly one.
`plan`	body	string	—	Plan is the plan the caller is served as ("dev", "max-5x", "max-20x", "team", "agency", "advisory", "dedicated", ...), "free" when none counts.
`session`	body	aiWindow	—
`session.percent`	body	integer (int64)	—	Percent is the share used, 0 to 100, rounded up to the next five so any use shows.
`session.resets_at`	body	string	—	ResetsAt is when the window starts again (RFC3339), null for a session that is not running: it starts at the next request.
`session.state`	body	string	—	State is ok, near (four fifths used) or limited (used up).
`state`	body	string	—	State is the worst class's: ok, near or limited.
`upgrade`	body	string	—	Upgrade is the plan that raises these limits, absent at the top.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo ai limits get

.ts

.py

.go

.rs

.java

import { Configuration, AiApi } from 'hanzoai';

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

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AiApi(client).ai_limits()

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

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

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

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

let result = ai_api::ai_limits(&cfg, Default::default()).await?;

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

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

var result = new AiApi(client).aiLimits();

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

Tool ai, op aiLimits — 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": "ai",
         "arguments": {
           "op": "aiLimits",
           "input": {}
         }
       }
     }'

AI API · All Hanzo APIs · Interactive reference

Was this page useful?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousCreate generations — POST /v1/frame/generations NextList tools