TETR.IO Tetra Channel API

Free TETR.IO Tetra Channel API with no key: player records, TETRA LEAGUE ranks, global leaderboards and live service-wide statistics. Tested example and real response.

No API key requiredHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the TETR.IO Tetra Channel API?

The Tetra Channel API is TETR.IO's official read-only API. It exposes player profiles, personal records, TETRA LEAGUE standings, leaderboards and service-wide statistics such as total accounts and games played, with no API key or account required.

Every response carries a `cache` object, and this is not decoration — the API is built around the expectation that you will honour it. `cached_at` and `cached_until` tell you exactly how long the current answer is valid, and re-requesting before it expires returns the same numbers while adding load. There is a third `status` value beyond hit and miss: `awaited`, meaning another client triggered the upstream fetch and your request queued behind it. Caches are also per-worker, so a load balancer can hand you slightly different snapshots on consecutive calls.

The timestamps are milliseconds, not seconds. `cached_at: 1787298389984` is thirteen digits, and feeding that to a seconds-based date constructor lands you fifty thousand years in the future — a bug that survives review easily because the number looks plausible. The other constraint is CORS: the API reflects only `https://tetr.io` as an allowed origin, so browser code on your own domain cannot call it. Proxy through a server, and while you are there send the `X-Session-ID` header the docs ask for on related requests.

Quick facts

Base URL: https://ch.tetr.io/api
Authentication: No key or account. The documentation asks for an `X-Session-ID` header on sequences of related requests so the service can keep your data consistent and reduce load.
Rate limit: No numeric limit is published. The guidance is roughly one request a second with short bursts tolerated, and to honour the `cache` object rather than polling.
Pricing: Free, operated by the TETR.IO team.
CORS: Not enabled — call it from your server
Official docs: Read the docs

How to use the TETR.IO Tetra Channel API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch live TETR.IO service statistics

GET https://ch.tetr.io/api/general/stats

curl

curl 'https://ch.tetr.io/api/general/stats'

JavaScript (fetch)

const res = await fetch("https://ch.tetr.io/api/general/stats");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

res = requests.get("https://ch.tetr.io/api/general/stats", timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200

{
  "success": true,
  "data": {
    "usercount": 9576110,
    "usercount_delta": 0.12236050901971753,
    "anoncount": 6186957,
    "totalaccounts": 26615095,
    "rankedcount": 34079,
    "recordcount": 200688872,
    "gamesplayed": 1065376750,
    "gamesplayed_delta": 6.135505523702979,
    "gamesfinished": 848828956,
    "gametime": 182984737427.48126,
    "inputs": 689850294589,
    "piecesplaced": 161261697989
  },
  "cache": {
    "status": "miss",
    "cached_at": 1787298389984,
    "cached_until": 1787298449984
  }
}

Parameters

Parameter	Type	Required	Description
`user`	path segment	Optional	Username or user id on `/users/{user}` for a player profile. `osk`
`records`	path segment	Optional	Appended to a user path to fetch their personal bests instead of their profile. `records`
`X-Session-ID`	header	Optional	An arbitrary identifier you keep stable across related requests, so the API can serve you a consistent snapshot. `my-app-4f2c`

Response fields

successboolean: Whether the request succeeded at the application level. Check this, not just the HTTP status.
dataobject: The payload. On `/general/stats` it holds the service-wide counters.
data.usercount / anoncount / totalaccountsinteger: Registered users, anonymous players, and the total of both. They do not sum the way you might guess, so read all three rather than deriving one.
data.usercount_delta / gamesplayed_deltafloat: Rate of change per second at the moment of the snapshot — a live-ticker value, not a cumulative figure.
data.gametimefloat: Total seconds played across the service. A float, and large enough to lose precision if you cast it carelessly.
cache.statusstring: `hit`, `miss` or `awaited` — the last meaning another client's fetch is already in flight and yours queued behind it.
cache.cached_at / cached_untilinteger: Unix timestamps in MILLISECONDS, not seconds. Divide by 1000 before constructing a date.

What you can build with the TETR.IO Tetra Channel API

Show a player's TETRA LEAGUE rank and rating on a profile page
Build a leaderboard mirror for a community tournament
Track a player's personal bests over time
Display live service statistics on a community dashboard
Verify a player's rank before seeding a bracket

Common errors and how to fix them

success: false with HTTP 200

The request was understood but could not be fulfilled — usually an unknown username.

Fix: Branch on the body's `success` field. Relying on the status code alone will treat failures as successes.

A CORS error in the browser

The API allows only `https://tetr.io` as an origin.

Fix: Call it from your server. There is no key to protect, so a thin proxy is all you need.

Dates fifty thousand years in the future

You passed `cached_at` to a seconds-based date constructor.

Fix: The timestamps are milliseconds. Divide by 1000 for anything expecting seconds.

Inconsistent numbers between calls

Cache is not shared between workers, so load balancing can return different snapshots.

Fix: Send a stable `X-Session-ID` on related requests, and do not treat small discrepancies as data corruption.

TETR.IO Tetra Channel API — frequently asked questions

Does the TETR.IO API need an API key?

No. The Tetra Channel API is read-only and entirely open — no key, no account, no bot registration. The documentation asks only that you keep request rates modest and honour the cache expiry in each response.

Why are TETR.IO timestamps so large?

They are Unix timestamps in milliseconds rather than seconds, so they carry thirteen digits instead of ten. Divide by 1000 before handing them to anything that expects seconds, or your dates will land tens of thousands of years out.

Can I call the TETR.IO API from a browser?

Not from your own domain. The API only allows `https://tetr.io` as a cross-origin caller, so a front-end fetch will be blocked. Route the call through your own server instead — there is no secret to protect, so the proxy can be trivial.

What does cache status 'awaited' mean?

Another client requested the same resource and its upstream fetch is still in flight, so your request waited on that instead of starting a second one. It is a normal, healthy state — the data is fresh, it just was not fetched on your behalf.

Tools that pair with this API

Timestamp Converter

Convert timestamps to human-readable dates and dates back to timestamps. Auto-detects seconds vs milliseconds, shows local, UTC and ISO 8601 formats.

Unix Timestamp Converter

Unix epoch time converter with live current epoch, seconds, milliseconds and microseconds support, and a reference table of common epoch values.

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

TETR.IO Tetra Channel is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.