Language levels

Read a summary without book access

Use GET /api/v1/levels with only levels:read and a monthly cap of 0. There is no levels MCP tool. This scope cannot read books, raw reading history, email or billing, change levels or spend credits. Results always belong to the key's account. There is no account selector.

See the copy-paste curl, TypeScript and Python examples. Store the key on your server and never in frontend code.

Select languages

Pass one optional comma-separated languages parameter, such as en,es,ja,ko,fr. Use canonical language codes. Omit it to include languages recorded in learning, native or known settings, claims, books or reading. Unknown parameters or languages, regional aliases, repeated parameters and an empty list return 400 invalid_request.

Understand the answer

{
  "calculatedAt": "2026-10-16T12:00:00.000Z",
  "languages": [
    {"code":"en","status":"native","displayLevel":null,"native":true,"explanationUrl":"https://app.alloglot.com/levels/en?level=native#level-native"},
    {"code":"es","status":"available","displayLevel":"3","native":false,"explanationUrl":"https://app.alloglot.com/levels/es?level=3#level-3"},
    {"code":"fr","status":"unavailable","displayLevel":null,"native":false,"explanationUrl":"https://app.alloglot.com/levels/fr"}
  ]
}

This is illustrative data, not an account's verified levels. Treat displayLevel as a string. Native languages have no numeric level. Unavailable means no usable estimate, not zero. A recorded beginner may have a real 0.1 without reading. Beginner labels are 0.0–0.5 and graduate labels 10.0–10.9. Do not invent 0.6–0.9 or replace null with zero.

The effective level follows the app's reading calculation and saved claims or baseline. A manually selected level can differ from the measured level. Raw reading inputs are never returned. These are reading estimates, not standardized proficiency certifications.

The public English level guide and Spanish level guide need no sign-in. Each returned explanationUrl links to that language's guide and, when available, the matching level. The guides contain no account data.

Refresh without losing a good snapshot

Fetch from your server about hourly. The endpoint uses Cache-Control: no-store. Keep the last validated 200 snapshot privately, with its original calculatedAt. Publish only the level summary you intended to share, never the key. Replace it only after validating a successful response. During network errors, 429 or 5xx, keep the previous snapshot and back off. A failed read must not become an empty or zero success.

The default key rate is 60 calls a minute across REST and MCP. Respect 429 Retry-After and retryAfterSeconds. Persistent 401 or 403 requires checking credentials or scope. A 404 can mean your account is outside early access. See errors and safe retries.

Revocation stops future calls immediately. It cannot recall a retained or published snapshot. Remove that snapshot from your service when disconnecting. See Your data and connected agents.