Check your allowance

GET /api/cli/free-tier returns the allowance of the account that owns the API key: which Pass it holds, how much of the current 7-day window is used, and when the window resets. It is meant for tools that only have a key, such as an editor plugin or a coding agent that wants to show a usage bar.

The figures are the ones on the allowance card in Dashboard, read from the same place.

Request

curl https://tokenharbor.ai/api/cli/free-tier \
  -H "Authorization: Bearer $TOKEN_HARBOR_API_KEY"

const res = await fetch("https://tokenharbor.ai/api/cli/free-tier", {
  headers: { Authorization: `Bearer ${process.env.TOKEN_HARBOR_API_KEY}` },
});
if (!res.ok) throw new Error(`allowance lookup failed: ${res.status}`);
const a = await res.json();
if (a.on_plan) {
  console.log(`${a.plan_name}: ${a.plan_used_pct}% of this week used`);
}

• Any of your API keys works. There are no parameters: the account is always the one the key belongs to, and a key cannot read another account.
• The call is read-only and free.

Rate limits

• Checking your allowance does not count against your request rate limit or use any of your allowance.
• The answer may be cached for 15 seconds (Cache-Control: private, max-age=15), so asking more often returns the same figures. Once a minute is plenty for a status bar.

Response

An account on the Office Pass, partway through its window:

{
  "plan_name": "Office Pass",
  "on_plan": true,
  "plan_used_pct": 37,
  "plan_exhausted": false,
  "used_pct": 12,
  "exhausted": false,
  "activated": true,
  "period_started_at": "2026-11-05T09:12:44.512+00:00",
  "period_ends_at": "2026-11-12T09:12:44.512+00:00",
  "reset_at": "2026-11-12T09:12:44.512+00:00",
  "models": ["deepseek-v4.1-flash:free", "mimo-v2.6-flash:free"],
  "models_enabled": true
}

The model ids in models are an example; the response always carries the current list.

Pass allowance

Free allowance

The window

The Pass allowance and the free allowance are measured separately but share one window, so a single reset_at applies to both. Buying a Pass or moving to a bigger one starts a new window; see How included usage refreshes.

Other fields may appear in the response. They are kept for older clients, are not part of this contract, and should be ignored.

What the numbers are

• Percentages, not amounts. The response does not say how many dollars of allowance are used or left. What each Pass includes is listed on Plans, and how usage is valued is described in Subscription.
• Rounded to whole numbers. Use plan_exhausted and exhausted to decide whether calls will be refused; a percentage reading 100 and the *_exhausted flag turning true do not always happen on the same request.
• Same window as the dashboard. The bar in the dashboard and this response are computed by the same lookup, so they agree up to the 15-second cache.

Errors