API Documentation
The Tomato.gg API lets you access player and tank data programmatically. Generate an API key from your Account page and pass it on every request via the x-api-key header. Requests are rate limited to 60 requests / minute per key.
Base URL
https://api.tomato.gg
Authentication
| Name | Type | Description |
|---|---|---|
| x-api-key | string | Your API key, prefixed with tmgg_. Sent as a request header on every call. |
Path parameters shown as :server accept the Wargaming region codes com, eu and asia. Player IDs are Wargaming account IDs.
Errors
Failed requests return a JSON body with the HTTP status: 401 for a missing or invalid key, 403 for a private profile you aren't authorised to read, and 429 when you exceed 60 requests / minute.
{
"meta": { "status": "error", "code": 429 },
"error": "Rate limit exceeded. Try again in 60 seconds."
}Recent Player Stats
GET/api/player/recents/:server/:id
Returns a player's recent statistics, computed over the requested day periods and/or battle counts. Stats are derived by diffing the player's current totals against stored snapshots.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| days | string | Comma-separated list of day periods to compute stats over, e.g. 30,60,90. |
| battles | string | Comma-separated list of recent battle counts to compute stats over, e.g. 100,500,1000. |
| cache | string | When true, only returns a cached result and responds with 404 if none is available. |
Example request
curl "https://api.tomato.gg/api/player/recents/com/1001234567?days=30,60&battles=100" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "id": 1001234567, "cached": false, "status": "good" },
"data": {
"days": {
"30": { /* recent stats for the last 30 days */ },
"60": { /* recent stats for the last 60 days */ }
},
"battles": {
"100": { /* recent stats for the last 100 battles */ }
}
}
}Overall Player Stats
GET/api/player/overall/:server/:id
Returns a player's lifetime (overall) statistics, including per-tank stats, achievements and DPG rankings.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| cache | string | When true, only returns a cached result and responds with 404 if none is available. |
Example request
curl "https://api.tomato.gg/api/player/overall/com/1001234567" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "id": 1001234567, "cached": false },
"data": { /* overall summary, per-tank stats, achievements, rankings */ }
}Player Sessions
GET/api/player/sessions/:server/:id
Returns the player's recorded stat sessions, grouped by day, week and month. Each grouping summarises performance across that period.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| days | number | Limit sessions to the last N days. |
| showTanks | "true" | "false" | Include per-tank breakdowns within each session. Defaults to "false". |
| cache | string | When true, only returns a cached result and responds with 404 if none is available. |
Example request
curl "https://api.tomato.gg/api/player/sessions/com/1001234567?days=30&showTanks=true" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "id": 1001234567, "cached": false },
"data": {
"sesday": [ /* daily sessions */ ],
"sesweek": [ /* weekly sessions */ ],
"sesmonth": [ /* monthly sessions */ ]
}
}Overall Stats Tracker
GET/api/player/overall-tracker/:server/:id
Returns the player's overall stats over time, ordered by total battles. Useful for plotting how lifetime WN8, win rate and other averages have evolved.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
| id | number | The player's Wargaming account ID. |
Example request
curl "https://api.tomato.gg/api/player/overall-tracker/com/1001234567" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "id": 1001234567 },
"data": [
{ "battles": 1000, "wn8": 1850, "wnx": 1790, "winrate": 52.1, "dpg": 1900, "frags": 1.1, "survived": 41.2, "spots": 1.3, "damageReceived": 1600, "xp": 620 }
]
}Player Rankings
GET/api/player/rankings/:server/:id/:type
Returns a player's leaderboard rankings, both overall and per-tank. Choose between lifetime (overall) and recent rankings.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
| id | number | The player's Wargaming account ID. |
| type | "overall" | "recent" | Which ranking set to return. |
Example request
curl "https://api.tomato.gg/api/player/rankings/com/1001234567/overall" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good" },
"data": {
"overall": { /* overall ranking */ },
"tanks": [ /* per-tank rankings */ ]
}
}Player Map Stats
GET/api/player/map-stats/:id
Returns a player's per-map performance for standard random battles, including WN8, win rate and a wide set of per-battle averages. Set detailed=true to break results down by battle type.
Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| days | number | Only include battles from the last N days. |
| detailed | "true" | "false" | When true, splits each map by battle type (standard / encounter / assault). |
| tiers | string | Comma-separated tier filter (booleans for tiers 1–11). |
| classes | string | Comma-separated class filter (HT, MT, LT, TD, SPG). |
| nations | string | Comma-separated nation filter. |
| tankId | number | Restrict to a single tank. |
Example request
curl "https://api.tomato.gg/api/player/map-stats/1001234567?days=90&detailed=true" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "player_id": 1001234567 },
"data": [
{ "display_name": "Prokhorovka", "battles": 42, "winrate": 54.8, "WN8": 2100, "avg_damage": 2300, /* ... */ }
]
}Onslaught Progression
GET/api/player/onslaught/:id
Returns a player's Onslaught rating progression over the last 60 days. Calibration battles (rating 0) are excluded.
Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
Example request
curl "https://api.tomato.gg/api/player/onslaught/1001234567" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good" },
"data": [
{ "arena_id": 123456789, "battle_time": 1748736000000, "rating": 2450, "delta": 25, "tank_id": 5137 }
]
}Individual Tank Sessions
GET/api/player/tank-sessions/:server/:id/:tankid
Returns a single tank's session history for a player, bucketed by day, week and month. Each record includes WN8 and the core per-battle averages for that period.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
| id | number | The player's Wargaming account ID. |
| tankid | number | The tank ID to fetch sessions for. |
Example request
curl "https://api.tomato.gg/api/player/tank-sessions/com/1001234567/5137" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"day": [ { "timestamp": "2026-06-01T00:00:00.000Z", "battles": 12, "winrate": 58.3, "dpg": 2450, "WN8": 2310, /* ... */ } ],
"week": [ /* weekly buckets */ ],
"month": [ /* monthly buckets */ ]
}Tank Recent Stats
GET/api/player/tank-recents/:server/:id/:tankId
Returns recent performance for a single tank across fixed look-back windows (1, 3, 7, 14, 30, 60 and 120 days). Periods with no battles return null fields.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
| id | number | The player's Wargaming account ID. |
| tankId | number | The tank ID to fetch recent stats for. |
Example request
curl "https://api.tomato.gg/api/player/tank-recents/com/1001234567/5137" \ -H "x-api-key: tmgg_your_key_here"
Example response
[
{ "period": "1 Day", "battles": 8, "winrate": 62.5, "dpg": 2600, "wn8": 2450, "wnx": 2380, /* ... */ },
{ "period": "7 Days", "battles": null, "winrate": null, "wn8": null, /* ... */ }
]MoE Progression
GET/api/player/moe-progression/:id/:tankId
Returns a player's Mark of Excellence progression for a single tank in random battles, ordered chronologically.
Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
| tankId | number | The tank ID to fetch MoE progression for. |
Example request
curl "https://api.tomato.gg/api/player/moe-progression/1001234567/5137" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good" },
"data": [
{ "moe": 91.2, "moe_diff": 0.4, "battle_time": 1748736000000, "damage": 2400, "tracking_assist": 120, "spotting_assist": 300 }
]
}Player Battles (Advanced)
GET/api/player/battles/:idAuth required
Returns a paginated list of a player's battles from the advanced battle log, including loadouts (equipment, shells, consumables, field mods), per-battle WN8/WNX and full combat details.
Authentication. Subject to the player's visibility settings. Private profiles require an authenticated request from the owner and otherwise respond with
403.Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| page | number | Zero-based page index. Defaults to 0. |
| pageSize | number | Rows per page. Defaults to 10. |
| days | number | Only include battles from the last N days. Defaults to 365. |
| battleType | string | Game mode filter (e.g. random battles, frontline, onslaught). |
| tankId | number | Restrict to a single tank. |
| mapId | number | Restrict to a single map. |
| arenaId | number | Restrict to a single battle arena. |
| sortBy | string | Column to sort by. Defaults to battle_time. |
| sortDirection | "asc" | "desc" | Sort direction. Defaults to desc. |
| platoon | string | One of "in-platoon", "outside-platoon", "in-and-outside-platoon" (default). |
| spawn | "first" | "second" | "all" | Filter by spawn side. |
| won | "won" | "lost" | "draw" | "all" | Filter by battle outcome. |
| tankType | "tech-tree" | "premium" | "all" | Filter by tank type. |
| classes | string | Comma-separated class filter (HT, MT, LT, TD, SPG). |
| nations | string | Comma-separated nation filter. |
| tiers | string | Comma-separated tier filter. |
Example request
curl "https://api.tomato.gg/api/player/battles/1001234567?page=0&pageSize=10&won=won" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "player_id": 1001234567, "page": 0 },
"data": [ { "tank_id": 5137, "damage": 3200, "frags": 3, "won": true, "wn8": 2900, "equipment": [ /* ... */ ], /* ... */ } ]
}Player Battles (Common)
GET/api/player/common-battles/:idAuth required
Returns a paginated list of a player's battles from the common battle log. Lighter than the advanced log (no loadout data) but available for more battles.
Authentication. Subject to the player's visibility settings. Private profiles require an authenticated request from the owner and otherwise respond with
403.Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| page | number | Zero-based page index. Defaults to 0. |
| pageSize | number | Rows per page. Defaults to 10. |
| days | number | Only include battles from the last N days. Defaults to 365. |
| battleType | string | Game mode filter (e.g. random battles, frontline, onslaught). |
| tankId | number | Restrict to a single tank. |
| mapId | number | Restrict to a single map. |
| arenaId | number | Restrict to a single battle arena. |
| sortBy | string | Column to sort by. Defaults to battle_time. |
| sortDirection | "asc" | "desc" | Sort direction. Defaults to desc. |
| platoon | string | One of "in-platoon", "outside-platoon", "in-and-outside-platoon" (default). |
| spawn | "first" | "second" | "all" | Filter by spawn side. |
| won | "won" | "lost" | "draw" | "all" | Filter by battle outcome. |
| tankType | "tech-tree" | "premium" | "all" | Filter by tank type. |
| classes | string | Comma-separated booleans for HT, MT, LT, TD, SPG (in that order). |
| nations | string | Comma-separated booleans for each nation (Germany, USSR, USA, France, UK, China, Japan, Czech, Poland, Sweden, Italy). |
| tiers | string | Comma-separated booleans for tiers 1–11. |
Example request
curl "https://api.tomato.gg/api/player/common-battles/1001234567?page=0&pageSize=10" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "player_id": 1001234567, "page": 0 },
"data": [ { "tank_id": 5137, "damage": 3200, "frags": 3, "won": true, "wn8": 2900, "wnx": 2840, /* ... */ } ]
}Player Battles (Combined)
GET/api/player/combined-battles/:idAuth required
Returns a paginated list of battles from the common log, enriched with advanced-log details and loadouts where available. Each row carries an isAdvanced flag. Page size is capped at 10.
Authentication. Subject to the player's visibility settings. Private profiles require an authenticated request from the owner and otherwise respond with
403.Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| page | number | Zero-based page index. Defaults to 0. |
| pageSize | number | Rows per page. Defaults to 10. |
| days | number | Only include battles from the last N days. Defaults to 365. |
| battleType | string | Game mode filter (e.g. random battles, frontline, onslaught). |
| tankId | number | Restrict to a single tank. |
| mapId | number | Restrict to a single map. |
| arenaId | number | Restrict to a single battle arena. |
| sortBy | string | Column to sort by. Defaults to battle_time. |
| sortDirection | "asc" | "desc" | Sort direction. Defaults to desc. |
| platoon | string | One of "in-platoon", "outside-platoon", "in-and-outside-platoon" (default). |
| spawn | "first" | "second" | "all" | Filter by spawn side. |
| won | "won" | "lost" | "draw" | "all" | Filter by battle outcome. |
| tankType | "tech-tree" | "premium" | "all" | Filter by tank type. |
| classes | string | Comma-separated class values (e.g. HT,MT). |
| nations | string | Comma-separated nation values. |
| roles | string | Comma-separated role values. |
| tiers | string | Comma-separated tier numbers (e.g. 8,9,10). |
Example request
curl "https://api.tomato.gg/api/player/combined-battles/1001234567?page=0&pageSize=10" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "player_id": 1001234567, "page": 0 },
"data": [ { "tank_id": 5137, "damage": 3200, "won": true, "isAdvanced": true, "equipment": [ /* ... */ ], /* ... */ } ]
}Mod Sessions
GET/api/player/mod-sessions/:id
Returns a player's battles grouped into play sessions (a gap of more than six hours starts a new session), built from the advanced battle log with full loadouts.
Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| battleType | string | Game mode filter. |
| tankId | number | Restrict to a single tank. |
| map | string | Restrict to a single map (display name). |
| limit | number | Maximum number of sessions to return. Defaults to 14. |
Example request
curl "https://api.tomato.gg/api/player/mod-sessions/1001234567?limit=14" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "player_id": 1001234567 },
"data": [ { /* session summary + grouped battles */ } ]
}Battle Detail
GET/api/player/battle-detail/:id
Returns the full scoreboard for a single battle (all players), keyed by the battle's arena ID, along with general battle metadata (map, mode, duration).
Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The arena (battle) ID. |
Example request
curl "https://api.tomato.gg/api/player/battle-detail/123456789" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good" },
"general": { "map": "Prokhorovka", "battle_type": "standard", "duration": 412, "battle_time": "2026-06-01T12:00:00.000Z", /* ... */ },
"players": [ { "username": "PlayerName", "tank_id": 5137, "damage": 3200, "frags": 3, "won": true, /* ... */ } ]
}Battle Replay
GET/api/player/battle-replay/:playerId/:arenaId
Returns parsed replay data for a single player in a single battle, if a replay is available.
Path parameters
| Name | Type | Description |
|---|---|---|
| playerId | number | The player's Wargaming account ID. |
| arenaId | number | The arena (battle) ID. |
Example request
curl "https://api.tomato.gg/api/player/battle-replay/1001234567/123456789" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good" },
"data": { /* parsed replay data */ }
}Garage Equipment
GET/api/player/equipment/:idAuth required
Returns the player's garage loadout setup per tank (equipment, consumables, shells, field mods, directives and crew) as captured by the Tomato.gg mod.
Authentication. Subject to the player's loadout visibility settings. Private profiles require an authenticated request from the owner and otherwise respond with
403.Path parameters
| Name | Type | Description |
|---|---|---|
| id | number | The player's Wargaming account ID. |
Example request
curl "https://api.tomato.gg/api/player/equipment/1001234567" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good", "player_id": 1001234567 },
"created": "2026-05-01T00:00:00.000Z",
"updated": "2026-06-01T00:00:00.000Z",
"data": [ { "tankId": 5137, "name": "Object 140", "selectedSlot": [ /* equipment */ ], "crew": [ /* ... */ ], /* ... */ } ]
}Bulk Player Stats
GET/api/player/bulk-stats/:server
Returns recent and overall summary stats (battles, WN8, win rate, average tier) for many players at once, keyed by account ID.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
Query parameters
| Name | Type | Description |
|---|---|---|
| ids | string | Comma-separated list of player account IDs. |
Example request
curl "https://api.tomato.gg/api/player/bulk-stats/com?ids=1001234567,1007654321" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good" },
"data": {
"1001234567": {
"recent": { "battles": 120, "wn8": 2400, "winrate": 56.2, "avgTier": 9.1 },
"overall": { "battles": 25000, "wn8": 1850, "winrate": 52.0, "avgTier": 7.8 }
}
}
}Bulk Tank Stats
GET/api/player/bulk-tank-stats/:server
Returns overall per-tank stats (battles, damage, wins, WN8) for many players at once, keyed by account ID and then tank ID.
Path parameters
| Name | Type | Description |
|---|---|---|
| server | string | One of com, eu, asia. |
Query parameters
| Name | Type | Description |
|---|---|---|
| ids | string | Comma-separated list of player account IDs. |
Example request
curl "https://api.tomato.gg/api/player/bulk-tank-stats/com?ids=1001234567,1007654321" \ -H "x-api-key: tmgg_your_key_here"
Example response
{
"meta": { "status": "good" },
"data": {
"1001234567": {
"5137": { "battles": 540, "damage": 1080000, "wins": 300, "wn8": 2600 }
}
}
}