Credits

Check your credit allowance, usage, and reset date for the current billing period. This call requires an API key, costs no credits, and keeps answering after the allowance is spent. For prices and charging rules, see Credits and pricing.

Get your credit balance

get

API key only.

Never consumes credits.

Your API credit allowance and consumption for the current billing period. period_start, period_end and resets_at state it.

Each successful call costs the credits on the price list. A call that costs more than you have left is refused before it runs, and once your credits are spent every v1.2 endpoint — the free ones included — returns 429 with code credit_limit_exceeded until resets_at; retrying does not help before then.

Authorizations

AuthorizationstringRequired

Your credential, sent as Authorization: Bearer <credential>. Two kinds reach this API, and the prefix tells them apart.

API key (sk-…) — created in the Developer Dashboard, it authenticates your whole account. Use it only where you control the machine — never inside a mobile app or a browser. Every endpoint accepts it.

Client token (ct-…) — a short-lived credential bound to one of your end users, minted from your API key by POST /v1.2/auth/client-tokens on your backend and relayed to the device. Safe to hold on a phone: it expires within 2 hours and acts only as the user it was minted for. Endpoints that open with API key or client token accept one and name the scope it must carry; endpoints that open with API key only refuse it.

Responses

200

Your credit balance for the current billing period: the plan, the period bounds and reset instant, used_credits, and included_credits/remaining_credits — always present, and null for an uncapped partner whose plan has no ceiling.

application/json

planstring · enumRequired

The plan this allowance comes from. unlimited is a partner with no ceiling, for whom both ceiling fields are null.

Example: freePossible values:

period_startstring · dateRequired

First day of the current billing period (UTC), inclusive. In the month of a plan change that starts no new billing period (a move to Free, say), the day of the change, when the allowance restarted.

Example: 2026-08-01

period_endstring · dateRequired

Last day of the current billing period (UTC), inclusive.

Example: 2026-08-31

resets_atstring · date-timeRequired

When the billing period ends and the next begins: used_credits and the free-call count return to 0 and the request allowance reopens.

Example: 2026-09-01T00:00:00.000Z

included_creditsinteger · nullableRequired

Credits included in the plan for this period, or null when the plan has no ceiling.

Example: 1000

used_creditsintegerRequired

Credits used so far this period. Each successful call costs the credits on the price list; failed calls cost nothing.

Example: 342

remaining_creditsinteger · nullableRequired

Credits left in this period, or null when the plan has no ceiling.

Example: 658

401

The request carried no Authorization header, or the credential in it was rejected.

unauthorized — the header is missing or malformed, or the key is not one we recognise. A valid key belonging to the other API version is 403 forbidden instead.

A client token is rejected in one of three ways, and only the first should be handled automatically:

• token_expired — the token is past its TTL. Mint a fresh one from your backend and retry the request once. This is routine and expected once per TTL window.
• token_invalid — no such token: it was never issued, or it has been purged, which happens shortly after it expires. This code is not an automatic token-refresh signal.
• token_revoked — the token was revoked, by POST /v1.2/auth/client-token-revocations or from the dashboard. The end user signs in again in your app, and your backend decides whether to mint another; a device that just re-mints defeats the revocation.

application/json

403

The credential is valid but is not allowed to make this request. forbidden is the general case — a key issued for the other API version, for example. A client token adds client_token_not_allowed, meaning the endpoint takes only an sk- API key — its description opens with API key only. (in this API: POST /v1.2/auth/client-tokens, POST /v1.2/auth/client-token-revocations, POST /v1.2/chat/completions, POST /v1.2/literature/search, POST /v1.2/extractions, GET /v1.2/extractions/{job_id}, GET /v1.2/patients/{patient_id}/snapshot, and GET /v1.2/credits).

On an endpoint that opens with API key or client token., scope_insufficient means the token was minted without the scope named at the end of that endpoint’s description.

application/json

429

Balance reads are capped at 60 per minute by default (code: rate_limited), and that is the only limit on your account that applies here — neither your credit allowance nor the shared request limit does, so this 429 is never credit_limit_exceeded. Honor Retry-After when present, otherwise back off a few seconds; the window reopens one minute after your first read in it, so a retry shortly afterwards succeeds. A burst of traffic from a single IP can also be refused by the service-wide throttle, likewise with Retry-After.

application/json

default

Any other error: the HTTP status plus { code, message }. Retry only rate_limited and the transient 5xx codes.

application/json

get/v1.2/credits

GET /v1.2/credits HTTP/1.1
Host: partners.january.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "plan": "free",
  "period_start": "2026-08-01",
  "period_end": "2026-08-31",
  "resets_at": "2026-09-01T00:00:00.000Z",
  "included_credits": 1000,
  "used_credits": 342,
  "remaining_credits": 658
}