# TETR.IO API
> Live player, ranking and record data from TETR.IO, the massively-popular competitive online Tetris game, via its public API. TETR.IO is a multiplayer ranked game with millions of players. Get a player's profile together with their TETRA LEAGUE standing — their level (XP), games played and won, country and supporter status, plus their league rank letter, their TR rating, their global standing and the competitive stats that define a Tetris player: attack per minute, pieces per second and versus score. Pull a player's personal bests in the two solo modes, the 40-Lines sprint time and the Blitz score, each with its global rank. Get the top of the TETRA LEAGUE — the best ranked players in the world. Read TETR.IO's live global numbers — total accounts, ranked players, records set and games played. Live, no key, nothing stored. Distinct from other gaming and social-profile APIs — this is the TETR.IO TETRA LEAGUE and its players. Perfect for leaderboard, esports, gaming-community and stats apps.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tetrio-api/..."
```

## Pricing
- **Free** (Free) — 11,000 calls/Mo, 3 req/s
- **Starter** ($7/Mo) — 178,000 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 980,000 calls/Mo, 18 req/s
- **Business** ($44/Mo) — 5,500,000 calls/Mo, 40 req/s

## Endpoints

### Players

#### `GET /v1/records` — 40L sprint + Blitz personal bests

**Parameters:**
- `user` (query, required, string) — TETR.IO username Example: `caboozled_pie`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tetrio-api/v1/records?user=caboozled_pie"
```

**Response:**
```json
{
    "data": {
        "blitz": {
            "score": 1388599,
            "set_at": "2022-05-03T21:32:23.212Z",
            "global_rank": 28
        },
        "source": "TETR.IO",
        "username": "caboozled_pie",
        "sprint_40l": {
            "set_at": "2024-10-25T05:57:38.549Z",
            "global_rank": 19,
            "time_seconds": 15.403
        }
    },
    "meta": {
        "timestamp": "2026-06-10T14:02:23.533Z",
        "request_id": "9b83db91-e0b6-4076-9120-64179cd6fde2"
    },
    "status": "ok",
    "message": "Records retrieved successfully",
    "success": true
}
```

#### `GET /v1/user` — Player profile + TETRA LEAGUE standing

**Parameters:**
- `user` (query, required, string) — TETR.IO username Example: `caboozled_pie`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tetrio-api/v1/user?user=caboozled_pie"
```

**Response:**
```json
{
    "data": {
        "xp": 49012827,
        "role": "user",
        "league": {
            "tr": 24727.19,
            "vs": 437.19,
            "apm": 223.82,
            "pps": 3.91,
            "rank": "x+",
            "glicko": 4236.2,
            "games_won": 400,
            "games_played": 461,
            "global_standing": 3
        },
        "source": "TETR.IO",
        "country": "US",
        "username": "caboozled_pie",
        "games_won": 9511,
        "supporter": true,
        "badge_count": 33,
        "games_played": 16679,
        "win_rate_pct": 57.02
    },
    "meta": {
        "timestamp": "2026-06-10T14:02:23.729Z",
        "request_id": "ca2e47a7-a1ac-41e4-8028-9fba44463f22"
    },
    "status": "ok",
    "message": "User retrieved successfully",
    "success": true
}
```

### Rankings

#### `GET /v1/leaderboard` — Top TETRA LEAGUE players

**Parameters:**
- `limit` (query, optional, string) — Max 1-100 Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tetrio-api/v1/leaderboard?limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "source": "TETR.IO",
        "leaderboard": [
            {
                "tr": 24834.84,
                "vs": 472.87,
                "apm": 241.75,
                "pps": 4.33,
                "rank": "x+",
                "country": "KR",
                "position": 1,
                "username": "frozenaccount"
            },
            {
                "tr": 24795.6,
                "vs": 441.92,
                "apm": 220.38,
                "pps": 3.82,
                "rank": "x+",
                "country": "US",
                "position": 2,
                "username": "blaarg"
            },
            {
                "tr": 24727.19,
                "vs": 437.19,
                "apm": 223.82,
                "pps": 3.91,
                "rank": "x+",
                "country": "US",
                "position": 3,
                "username": "caboozled_pie"
            },
            {
                "tr": 24711.3,
                "vs": 425.11,
                "apm": 211.12,
                "pps": 3.78,
                "rank": "x+",
                "country": "PH",
                "position": 4,
                "username": "vincehd"
            },
            {
                "tr": 24687.82,
                "vs": 408.12,
                "apm": 212.54,
                "pps": 3.81,
                "rank": "x+",
                "country": "CN",
                "position": 5,
                "username": "kafe11"
 
…(truncated, see openapi.json for full schema)
```

### Stats

#### `GET /v1/stats` — TETR.IO live global stats

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tetrio-api/v1/stats"
```

**Response:**
```json
{
    "data": {
        "source": "TETR.IO",
        "records_set": 182900394,
        "total_users": 9919451,
        "games_played": 1028245047,
        "ranked_players": 39362,
        "total_accounts": 25846983,
        "anonymous_users": 6599247
    },
    "meta": {
        "timestamp": "2026-06-10T14:02:24.090Z",
        "request_id": "a8855a5d-f17b-4830-906c-c3b4fa304cf6"
    },
    "status": "ok",
    "message": "Stats retrieved successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/tetrio-api
OpenAPI spec: https://www.oanor.com/api/tetrio-api/openapi.json