# War Thunder Squadron Battle API

> Read-only JSON API over recorded War Thunder squadron-battle history: battles,
> per-player results, leaderboards, squadron ratings, vehicle data and
> battle-rating snapshots.
>
> No API key, no login, no JavaScript, no cookies. Every query is a plain GET
> URL with query-string parameters — fetch it once and you have the answer.

- Base URL: https://api.fzbot.top
- Also reachable as: https://fzbot.top/api/... (same data, same parameters)
- Full endpoint table in Markdown: https://api.fzbot.top/api/help
- Same table as JSON: https://api.fzbot.top/api/help?format=json
- Human-facing page: https://fzbot.top/

## How to call it

- **GET is enough.** Query endpoints take query-string parameters; POST with a
  JSON body works too but is never required.
- **Lists are comma-separated:** `member_names=A,B`, `session_ids=123,456`.
- **Times in requests** are unix seconds (`time_from` / `time_to`) or `YYYY-MM-DD` inside
  `session_key=range:...`. **Times in responses** are local-time strings like
  `"2026-10-21 02:25"` (UTC+8), not unix timestamps.
- **Battle count limit** is `max_battles` (`limit` is accepted as an alias).
- **No pagination tokens.** Use `limit` / `offset` where documented.
- **Read-only.** Nothing writes data; nothing needs an account.
- **Squadron tag casing.** In `/api/query` battle rows, `clans` keeps the original spelling while `clan_teams` keys are lowercase (`iZG0Y` vs `izg0y`). Compare case-insensitively when matching them.

## Ready-to-paste queries

Fetch any of these exactly as written.

```text
https://api.fzbot.top/api/db/status
https://api.fzbot.top/api/db/freshness
https://api.fzbot.top/api/query?session_key=range:2026-10-19:2026-10-19:noon:night
https://api.fzbot.top/api/db/timeline
https://api.fzbot.top/api/query?session_key=recent&max_battles=20
https://api.fzbot.top/api/query?tag=AVR&session_key=recent
https://api.fzbot.top/api/query/by-ids?session_ids=5391392491559117420
https://api.fzbot.top/api/battle/5391392491559117420
https://api.fzbot.top/api/battle/5391392491559117420/stats
https://api.fzbot.top/api/battle/5391392491559117420/roster
https://api.fzbot.top/api/battle/1331658428353492126/vehicles
https://api.fzbot.top/api/battle/5391392491559117420/log-chat?limit=50
https://api.fzbot.top/api/query/team-numbers?session_ids=5391392491559117420
https://api.fzbot.top/api/query/team-battles?session_ids=5391392491559117420&team_n=3
https://api.fzbot.top/api/players/search?q=night&limit=10
https://api.fzbot.top/api/player/103098928/summary?session_key=all
https://api.fzbot.top/api/player/103098928/vehicle/us_m4_t26
https://api.fzbot.top/api/vehicles/search?q=France+air+RB+4.0
https://api.fzbot.top/api/vehicles/search?type=light_tank&premium=0&limit=5
https://api.fzbot.top/api/vehicles/us_m1a2_abrams
https://api.fzbot.top/api/stats/vehicle/us_m1a2_abrams/players?limit=20
https://api.fzbot.top/api/vehicle/type-map
https://api.fzbot.top/api/vehicles/health
https://api.fzbot.top/api/stats/rank?session_key=recent&min_games=5
https://api.fzbot.top/api/stats/rank?session_key=recent&sort=win_rate&order=desc&min_games=10
https://api.fzbot.top/api/stats/rank?session_key=recent&team_sort=games&team_order=desc
https://api.fzbot.top/api/stats/lineup-rank
https://api.fzbot.top/api/clan/ranking?limit=20&sort=total&order=desc
https://api.fzbot.top/api/clan/rank-detail?tag=AVR
https://api.fzbot.top/api/clan/member-diff?tag=AVR
https://api.fzbot.top/api/clan/watch-teams?tags=AVR,TOP&per_clan=3
https://api.fzbot.top/api/squad/latest-vehicles?tag=AVR
https://api.fzbot.top/api/squad/vehicle-odds?tag=AVR&session_key=recent
https://api.fzbot.top/api/militia/latest-slot
https://api.fzbot.top/api/militia/slots
https://api.fzbot.top/api/militia/snapshots
https://api.fzbot.top/api/militia/weekly?days=7
```

Snapshot images are PNG. Call `latest-slot` first, then request images:

```text
https://api.fzbot.top/api/militia/img?slot=2026-10-20_afternoon&file=report_overview.png&mode=ground
```

## Parameters

### session_key

| Value | Meaning |
| --- | --- |
| `recent` | Most recent session slot (current, or the one just finished) |
| `today` | Today |
| `this_season` | Current season |
| `last_season` | Previous season |
| `all` | Everything on record (public window limit applies) |
| `range:FROM:TO:H1:H2` | Custom date range. **FROM/TO are `YYYY-MM-DD`**, not timestamps. H is one of `noon` (09:00-15:30), `night` (22:00-next 06:30), `morning` (06:30-15:30), `afternoon` (15:30-22:00), `am` (00:00-12:00), `pm` (12:00-24:00), `full` (whole day). Example: `range:2026-10-19:2026-10-19:noon:night` |

### Sorting

`sort` / `order` apply to players; `vehicle_sort` / `vehicle_order` to vehicles;
`team_sort` / `team_order` to teams. Keys: `games`, `kills`, `deaths`,
`assists`, `score`, `kd`, `kr`, `win_rate`. The response echoes the sort that
was applied.

### Filters

- `min_games` — drop rows below a game count (default 1)
- `member_names` — restrict to these players; also lifts the window limit
- `no_cache` — force a fresh computation

## Errors

| Code | Meaning |
| --- | --- |
| 400 | Unfiltered leaderboard window too wide (over 60 days). Add `member_names`, or use `range:YYYY-MM-DD:YYYY-MM-DD:noon:night` for an explicit ≤60-day window |
| 404 | Unknown path, or the battle / player / image does not exist |
| 422 | A parameter is invalid or required data is missing; the message says which |
| 503 | A heavy aggregation is already running; retry after `Retry-After` seconds |

## Limits

- **`night` spans midnight.** `range:2026-10-19:2026-10-19:noon:night` returns battles
  from 10-19 09:00 through 10-20 06:30, because the night slot belongs to the day it
  starts. For a calendar day use `am:pm` (00:00-24:00).
- Leaderboards without `member_names` cover up to 60 days on the public endpoint.
  `session_key=all` therefore always returns 400 on leaderboards — use
  `range:YYYY-MM-DD:YYYY-MM-DD:noon:night` for an explicit window instead.
  (`session_key=all` **is** valid on player endpoints such as `/api/player/{user_id}/summary`.)
- The lineup board defaults to the last 7 days; pass `session_key` for another window.
- Battles whose vehicles were never parsed return 404 on `/vehicles`; the read-only
  endpoint never triggers a download.
- Battle-card images return 404 until cached; the read-only endpoint never renders on demand.
- Snapshot images return 422 for slots that have not been synced yet.

## Full endpoint table

| Method | Path | Returns | Parameters |
| --- | --- | --- | --- |
| POST·GET | `/api/query` | Battles in a session, by squadron tag (empty tag = server-wide) | tag, seed_nicks, session_key, max_battles, min_hits, no_cache |
| POST·GET | `/api/query/by-ids` | Battle rows for a list of ids | session_ids[] |
| POST·GET | `/api/query/team-numbers` | Stable team numbering across queries | session_ids[], session_key, no_cache |
| POST·GET | `/api/query/team-battles` | All battles of one team inside a session | session_ids[], team_n, session_key |
| POST·GET | `/api/squad/latest-vehicles` | Vehicles spawned in each squad's most recent battle (scouting) | tag, seed_nicks, session_key |
| POST·GET | `/api/squad/vehicle-odds` | Vehicle usage share per player over a session | user_ids[], session_key, min_pct, mode=weighted|average |
| GET | `/api/session/range` | Start/end timestamps of the current 'recent' session | — |
| GET | `/api/battle/{session_id}` | Battle header: mission, mode, rosters, winner, row count | — |
| GET | `/api/battle/{session_id}/stats` | Per-player rows keyed by user_id | — |
| GET | `/api/battle/{session_id}/roster` | Rosters plus parse completeness | — |
| GET | `/api/battle/{session_id}/trajectory-status` | Whether a trajectory is available for this battle | — |
| GET | `/api/battle/{session_id}/vehicles` | Vehicles spawned in the battle | — |
| GET | `/api/battle/{session_id}/log-chat` | Battle log and in-game chat (parsed battles only) | — |
| POST·GET | `/api/stats/rank` | Player / vehicle / team leaderboards over the whole database | session_key, min_games, sort=kd|kr|kills|games|deaths|assists|score|win_rate, order=asc|desc, vehicle_sort, vehicle_order, team_sort, team_order, member_names[], time_from, time_to, no_cache |
| POST·GET | `/api/stats/lineup-rank` | Lineup win-rate ranking (8-vehicle multiset per side) | no_cache |
| GET | `/api/stats/vehicle/{craft}/players` | Players of one vehicle | limit, sort=kd|kr|kills|games, min_games, time_from, time_to, member_names[] |
| GET | `/api/player/{user_id}/summary` | Player career / session summary | session_key (all = career, recent = current session), top_crafts |
| GET | `/api/player/{user_id}/vehicle/{craft}` | Player results on one vehicle | — |
| GET | `/api/players/search` | Fuzzy player search | q |
| GET | `/api/clan/ranking` | Squadron table: official rank, score, members, bans | limit, sort=pos|tag|total|total_delta|rank_delta|members|banned_count|last_ts, order=asc|desc |
| GET | `/api/clan/rank-detail` | One squadron: score/rank history, roster changes, bans | tag |
| GET | `/api/clan/member-history` | Member rating history | — |
| GET | `/api/clan/member-diff` | Roster diff between snapshots | — |
| POST·GET | `/api/clan/watch-teams` | Latest battle per team for several squadrons | tags[], per_clan |
| GET | `/api/db/status` | Database summary (battles, parsed, pending) | none |
| GET | `/api/db/freshness` | Data freshness (latest battle age, pending parse, backup watermark) | none |
| GET | `/api/db/parse-health` | Unparsed battles within the compliance window (7 days) | none |
| GET | `/api/db/timeline` | Per-day battle counts | session_key, time_from, time_to |
| GET | `/api/db/anomaly-count` | Anomaly counters (unparsed / abandoned / stale) | none |
| GET | `/api/db/list-ids` | Session id list for export/paging | session_key, limit, filters (required) |
| GET | `/api/lang/names` | Localized display-name map (ASCII keys) | none |
| GET | `/api/lang/vehicle-name` | One vehicle display name | vid |
| GET | `/api/vehicle/type-map` | Vehicle id -> type map | none |
| GET | `/api/militia/latest-slot` | Latest completed battle-rating snapshot slot | mode=ground|air |
| GET | `/api/militia/report` | Battle-rating distribution as Markdown tables (same data as the PNG snapshots) | slot, mode=ground|air, format=md|json |
| GET | `/api/militia/img` | Battle-rating snapshot PNG | slot, file, mode=ground|air |
| POST·GET | `/api/db/list` | Database page rows (time, map, mode, download/parse status, replay id) | limit, offset, keyword, status, parse_status, session_key, time_from, time_to, after_start_time, after_session_id, air_side_gt, include_counts |
| GET | `/api/vehicles/search` | Fuzzy vehicle search (Chinese or English free text + structured filters) | q, country, type, mode, br_min, br_max, event, premium, squadron, feature, limit |
| GET | `/api/vehicles/{identifier}` | One vehicle in full (BR, role, features, wiki description) | identifier |
| GET | `/api/vehicles/health` | Vehicle dataset health (sync age, coverage, unknown vehicles) | none |
| GET | `/api/help` | This document (add ?format=json for a structured listing) | format=md|json |