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 — 37 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.*.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).
`credits_after_allowance`	body	boolean	—	CreditsAfterAllowance is the payer's choice to keep using a model on credits once the plan's included usage of it is spent (PUT /v1/ai/limits sets it).
`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).
`period_end`	body	string	—
`period_start`	body	string	—	PeriodStart and PeriodEnd bound the billing period (RFC3339).
`plan`	body	string	—	Plan is the plan the caller is served as ("dev", "max-5x", "max-20x", "team", "team-annual", "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 has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

.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?

PreviousCreate decisions — POST /v1/ai/mcp/decisions NextList tools