Skip to main content

Z.AI

Deep visibility for Z.AI coding subscriptions. Tracks the 5-hour and weekly rolling quota windows, monthly usage, per-model and per-tool breakdowns, and credit grants with expiry warnings.

At a glance​

  • Provider ID — zai
  • Detection — ZAI_API_KEY or ZHIPUAI_API_KEY (China fallback)
  • Auth — API key
  • Type — API platform (full billing data)
  • Tracks:
    • Coding models
    • 5-hour and weekly rolling quota usage percentage
    • Monthly usage
    • Per-model: requests, input/output/reasoning/cached tokens, cost (USD), tools
    • Tool usage: web search, web fetch, other
    • Credits: available, used (USD)
    • Credit grants list
    • Grants expiring in ≤30 days
    • Subscription status

Setup​

Auto-detection​

ZAI_API_KEY and ZHIPUAI_API_KEY are not interchangeable — they create separate accounts. Setting ZAI_API_KEY produces an account with id zai configured for the global region (api.z.ai); setting ZHIPUAI_API_KEY produces an account with id zhipuai-auto for the China region (open.bigmodel.cn). Both can be active simultaneously and will appear as separate tiles.

Manual configuration​

{
  "accounts": [
    {
      "id": "zai",
      "provider": "zai",
      "api_key_env": "ZAI_API_KEY",
      "base_url": "https://api.z.ai"
    }
  ]
}

Regional endpoints​

Z.AI has two regions:

Regionbase_urlNotes
Globalhttps://api.z.aiDefault
Chinahttps://open.bigmodel.cnUsed with ZHIPUAI_API_KEY

Data sources & how each metric is computed​

Z.AI splits its surface across two base URLs: a coding base for the model catalog and a monitor base for usage/credit data. Both are derived from the configured base_url.

RegionCoding baseMonitor base
Globalhttps://api.z.ai/api/coding/paas/v4https://api.z.ai
Chinahttps://open.bigmodel.cn/api/coding/paas/v4https://open.bigmodel.cn

Each poll (default every 30 seconds in daemon mode) hits up to five endpoints. All requests use Authorization: Bearer $ZAI_API_KEY (or $ZHIPUAI_API_KEY).

CallEndpointWhat it provides
1GET <coding>/modelsCoding model catalog
2GET <monitor>/api/monitor/usage/quota/limit5h/weekly window usage % + active subscription
3GET <monitor>/api/monitor/usage/model-usagePer-model request, token, cost samples
4GET <monitor>/api/monitor/usage/tool-usageWeb search, web fetch, other tool invocations
5GET <monitor>/api/paas/v4/user/credit_grantsCredit grants list with expiries

Coding model catalog​

  • Source: data[].id from <coding>/models.
  • Transform: stored under Raw["coding_models"]. The detail view renders one row per model.

5h_window / 7d_window — rolling quota usage​

  • Source: the quota/limit JSON. The body is wrapped in a monitor envelope; the inner data.limits array carries one row per window.
  • Transform: each windowed row (TOKENS_LIMIT, or CREDIT_LIMIT on credits-based plans) is routed by its unit/number pair — unit: 3, number: 5 is the 5-hour window, unit: 6, number: 1 is the weekly window. The percentage becomes usage_five_hour / usage_seven_day (Used against Limit = 100), and usage/currentValue become tokens_* or credits_* rows depending on the limit type, so credits plans show credits rather than tokens. Resets come from nextResetTime (epoch ms). Unsupported unit/number pairs are ignored instead of being labeled as 5-hour. The windows are rolling — not aligned to wall-clock — so heavy bursts push the gauges up quickly.
  • Legacy note: a TOKENS_LIMIT row with no unit/number predates the windowed shape and is still read as the 5-hour window.

Subscription status​

  • Source: a flag in the quota/limit response.
  • Transform: stored as Attributes["subscription_status"]. When no coding package is active, the value is inactive_or_free and the tile flags it.

:::note Cost values hidden by default on glm_coding_plan* Z.AI's coding packages (anything whose subscription status starts with glm_coding_plan) bill a flat package fee — the per-call dollar figures on model-usage are reference numbers, not what your card is charged. OpenUsage hides cost columns by default for those subscriptions; the 5h/weekly windows, monthly usage, and credit grants stay visible. Free / inactive_or_free accounts pay per-call and keep costs visible. Override with dashboard.hide_costs or the c keystroke. :::

Per-model rows​

  • Source: data of model-usage. Live payloads carry a per-model time series (modelDataList), a summary list repeated at the top level and inside totalUsage, and whole-window rollups (totalUsage.totalModelCallCount, totalUsage.totalTokensUsage). Older payloads used flat rows under data, each carrying a model name, request count, input/output/reasoning/cached tokens, cost in USD, and tool calls.
  • Transform: model rows are aggregated into usageRollup totals per model and emitted as detail rows. Reasoning and cached tokens are kept separate from input/output. Cost is in USD even on China endpoints.
  • Token totals are never read as request counts: totalTokensUsage feeds tokens and totalModelCallCount feeds requests, so a large token rollup no longer shows up as that many requests. A summary list repeated at several levels is only read once, so token totals are not multiplied.

Tool usage (web_search, web_fetch, other)​

  • Source: tool-usage response.
  • Transform: counted by name into Metrics["tool_web_search"], Metrics["tool_web_fetch"], and an aggregate tool_other for everything else.
  • Live payloads carry a per-tool breakdown (toolDataList) plus a toolSummaryList repeated at the top level and inside totalUsage, next to whole-window rollups (totalUsage.totalNetworkSearchCount, totalUsage.totalSearchMcpCount). A repeated summary is read once, and the total* rollups never surface as tool names; they only supply the window call total when the per-tool breakdown is empty.

credits_available / credits_used and grants​

  • Source: credit_grants response. Each grant has an amount, used amount, and an expire_at.
  • Transform: aggregate available and used are exposed as a single credit metric in USD. Each individual grant becomes a detail row; grants whose expire_at is within 30 days are flagged with a warning indicator.

Auth status​

  • Source: HTTP status code on any of the calls. 401/403 → auth; 429 → limited; otherwise ok. Plus monitor envelopes carry their own success flag — when false, the quota/limit call sets noPackage which becomes the inactive_or_free subscription state.

What's NOT tracked​

  • Daily spend chart. The monitor endpoints return totals and recent samples; no daily-spend series is produced.
  • Tool call cost. tool-usage reports counts, not per-call cost.

How fresh is the data?​

  • Polled every 30 s by default. The monitor surfaces are themselves rolling aggregates with their own update cadence.

API endpoints used​

  • GET <coding>/models
  • GET <monitor>/api/monitor/usage/quota/limit
  • GET <monitor>/api/monitor/usage/model-usage
  • GET <monitor>/api/monitor/usage/tool-usage
  • GET <monitor>/api/paas/v4/user/credit_grants

Caveats​

note

The 5-hour and weekly quota windows are rolling, not aligned to the wall clock. Heavy bursts of activity will push the gauges up quickly.

  • Subscription status reads inactive_or_free if no coding package is active.
  • Per-model cost is reported in USD even on China endpoints; reconcile against your invoice.
  • Reasoning and cached tokens are tracked separately from input/output.

Troubleshooting​

  • Subscription inactive_or_free — purchase a coding package in the Z.AI console.
  • No tool usage — the account has not made web-search or web-fetch calls yet.
  • Wrong region — switch between api.z.ai and open.bigmodel.cn and the matching env var.

"no package" or rejected key​

You are pointing at the wrong region. A ZAI_API_KEY issued for api.z.ai won't authenticate against open.bigmodel.cn, and ZHIPUAI_API_KEY is the China-region equivalent. Update base_url to match the console that issued the key.