Replace limits

Sets 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

AI → · All API references → · Get started →

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

Sets the payer's choice to keep using a model on credits once the plan's included usage of it is spent. A pooled org wallet is its org admin's to set; a person's own wallet is theirs. Every change is on the audit trail, before and after; no trail, no change. Answers the limits as they read after it.

Request

1 field, body application/json (required).

Field	In	Type	Required	Description
`creditsAfterAllowance`	body	boolean	—	CreditsAfterAllowance keeps a model working once the plan's included usage of it is spent, paid from prepaid credit (and granted credit where the model takes it), when true; when false the conversation moves to a Hanzo model and other calls are refused until the plan resets.

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.aiSetLimits({ creditsAfterAllowance: false });

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_set_limits(credits_after_allowance=False)

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

resp, _, err := client.AiAPI.AiSetLimits(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_set_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).aiSetLimits();

curl -X PUT https://api.hanzo.ai/v1/ai/limits \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "creditsAfterAllowance": false
     }'

MCP declares no tool for ai — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.

AI API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList models — GET /v1/ai/mcp/models NextDelete articles