# List limits URL: https://docs.hanzo.ai/docs/openapi/ai/ailimits > 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 →](https://docs.hanzo.ai/docs/openapi/ai) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | -------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/ai/limits` | | **Method** | `GET` | | **Operation** | `aiLimits` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | 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. Shares only, never amounts. ## 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](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** `hanzo` has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK. **SDK** **.ts** ```ts import { Configuration, AiApi } from 'hanzoai'; const api = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.aiLimits(); ``` **.py** ```python 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() ``` **.go** ```go 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 } ``` **.rs** ```rust 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?; ``` **.java** ```java 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(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/ai/limits \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** Tool `ai`, op `aiLimits` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash 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](https://docs.hanzo.ai/docs/openapi/ai) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)