---
title: "Player battles"
method: GET
path: "/{region}/players/{nickname}/battles"
tags: ["Players"]
---

# Player battles

`GET /{region}/players/{nickname}/battles`

## Request

- Base URL: `https://unicum.gg/api`
- URL: `https://unicum.gg/api/{region}/players/{nickname}/battles`
- Auth: none required

A player's most recent battles: the map, the mode, the vehicle they brought and what it did, newest first. Wargaming publishes an account's running totals and nothing about a single battle, so every battle here exists only because somebody who was in it runs the unicum.gg mod and shares them. A player's history therefore begins the day someone in their battles started sharing, and an empty list means nobody has, not that they have not played. 404 when the nickname is unknown in this region.

## Path parameters

- `region` 'eu' | 'na' | 'asia', required: Game server region.
- `nickname` string, required: Player nickname.

## Query parameters

- `limit` integer: Battles to return, newest first. Ten by default.

## Response `200`

Successful response

- PlayerBattlesResponse: A player's most recent battles, as the clients that played them reported.
  - `accountId` number, required
  - `nickname` string, required: The nickname this account carries now, which may differ from the one asked for.
  - `battles` PlayerBattle[], required: Newest first.
    - `id` string, required: The game's own battle id. A string, not a number: it runs to 19 digits, past what JSON carries.
    - `startedAt` string, date-time, required: When the battle started, from the game's own clock rather than our receipt.
    - `map` string, required: The arena's name, `45_north_america`, not its display title.
    - `mapBounds` object, nullable, required: The arena's extent in metres, which is what places a replay's coordinates on the minimap.
      - `bottomLeft` object, required
        - `x` number, required
        - `z` number, required
      - `upperRight` object, required
        - `x` number, required
        - `z` number, required
    - `mapImage` string, nullable, required: The minimap this battle was actually played on, resolved against the maps catalogue for this battle's own mode. Onslaught redraws most maps into a smaller play area and ships that as its own `_comp7` image, so a `comp7` battle is given that picture rather than the full-size one shipped under the arena's name, whether the arena is an Onslaught-only one or a map that also runs random battles.
    - `mapOverlay` MapOverlay, required
      - `bounds` object, required
        - `bottomLeft` object, required
          - `x` number, required
          - `z` number, required
        - `upperRight` object, required
          - `x` number, required
          - `z` number, required
      - `widthMeters` number, required
      - `heightMeters` number, required
      - `bases` object, required
        - `team1` Marker[], required
          - `left` number, required
          - `top` number, required
        - `team2` Marker[], required
          - `left` number, required
          - `top` number, required
      - `spawns` object, required
        - `team1` Marker[], required
          - `left` number, required
          - `top` number, required
        - `team2` Marker[], required
          - `left` number, required
          - `top` number, required
      - `controlPoint` Marker, required
        - `left` number, required
        - `top` number, required
      - `pois` object[], required
        - `marker` Marker, required
          - `left` number, required
          - `top` number, required
        - `type` number, required
    - `gameplay` string, nullable, required: `ctf`, `domination`, `assault`… null when none was named.
    - `battleType` number, required: The game's own `bonusType`: 1 random, 43 onslaught, 20/21 skirmishes.
    - `duration` number, nullable, required: Seconds.
    - `team` number, required: The player's own team.
    - `outcome` string, required: Win, loss or draw for this player; unknown when no winner was named.
    - `tank` BattleTank, required: A vehicle as a battle row names it.
      - `id` number, required: `typeCompDescr`, which is the catalogue's own tank id.
      - `name` string, required
      - `shortName` string, required
      - `tier` number, required
      - `type` string, required: `mediumTank`, `heavyTank`, …
      - `nation` string, required
      - `tag` string, required: The client's own tag, which the icon is addressed by.
      - `slug` string, nullable, required: Our slug for the vehicle page, null when it has none.
    - `own` BattleVehicle, required: One vehicle's whole battle.
      - `id` number, required: Battle-scoped vehicle id, the key the results are mapped by.
      - `account` number: Wargaming account id, absent for a bot.
      - `team` number, required
      - `tank` number, required: `typeCompDescr` of the vehicle the account brought.
      - `damage` number, required
      - `radio` number, required: Damage assisted by spotting.
      - `track` number, required: Damage assisted by tracking.
      - `stun` number, required: Damage assisted by stunning.
      - `blocked` number, required: Damage blocked by armour.
      - `received` number, required
      - `shots` number, required
      - `hits` number, required
      - `piercings` number, required
      - `spotted` number, required
      - `kills` number, required
      - `lifeTime` number, required: Seconds alive; the battle's duration when they survived it.
      - `deathReason` number, required: `-1` when they survived, otherwise the game's own reason code, of which 0 is one.
      - `capturePoints` number, required
      - `xp` number, required
      - `credits` number, required
      - `health` number, required: Hit points left, negative on the shot that overkills.
      - `maxHealth` number, required
    - `rating` object, required: What this one battle scored, keyed by metric (`wn7`, `wn8`, `wnx`). The same accumulators the lifetime figures use, fed a single battle: the ratings are defined per battle and only ever averaged. Null for a metric whose expected values do not carry this vehicle.
    - `devices` LoadoutSlot[]: The optional devices this account had fitted, by slot, as pictures only. A free slot is a null in place; a slot that was filled with something no catalogue here can picture is an object with a null image, which is a different thing. Absent for almost every battle: a loadout exists only where a recording of it carried one. The first life's, in a mode with respawns. Names are not here on purpose, since naming them would make this list vary by language and cost it its shared cache; the battle's own panel names everything.
      - `name` string, nullable, required: The item's name in the reader's language, or null for a free slot. Here so a preview box can carry a tooltip: ten unlabelled pictures say very little. It is why this endpoint is privately cached rather than shared.
      - `filled` boolean, required: Whether the slot is occupied. Said outright because a row carries no names to infer it from, and because a slot filled with something no catalogue here can picture must not read as an empty one.
      - `image` string, nullable, required: The item's picture, or null where Wargaming publishes none.
      - `overlay` string, nullable, required: The grade badge drawn in the corner, which is what tells a Bounty device from an ordinary one: the picture underneath is the same.
      - `categories` string[]: The Equipment 2.0 categories the game dots the box with.
    - `boosters` LoadoutSlot[]: Directives fitted, by slot, as pictures. Absent when none were, which is the usual case.
      - `name` string, nullable, required: The item's name in the reader's language, or null for a free slot. Here so a preview box can carry a tooltip: ten unlabelled pictures say very little. It is why this endpoint is privately cached rather than shared.
      - `filled` boolean, required: Whether the slot is occupied. Said outright because a row carries no names to infer it from, and because a slot filled with something no catalogue here can picture must not read as an empty one.
      - `image` string, nullable, required: The item's picture, or null where Wargaming publishes none.
      - `overlay` string, nullable, required: The grade badge drawn in the corner, which is what tells a Bounty device from an ordinary one: the picture underneath is the same.
      - `categories` string[]: The Equipment 2.0 categories the game dots the box with.
    - `consumables` LoadoutSlot[]: Consumables carried, by slot, as pictures.
      - `name` string, nullable, required: The item's name in the reader's language, or null for a free slot. Here so a preview box can carry a tooltip: ten unlabelled pictures say very little. It is why this endpoint is privately cached rather than shared.
      - `filled` boolean, required: Whether the slot is occupied. Said outright because a row carries no names to infer it from, and because a slot filled with something no catalogue here can picture must not read as an empty one.
      - `image` string, nullable, required: The item's picture, or null where Wargaming publishes none.
      - `overlay` string, nullable, required: The grade badge drawn in the corner, which is what tells a Bounty device from an ordinary one: the picture underneath is the same.
      - `categories` string[]: The Equipment 2.0 categories the game dots the box with.
    - `shells` object[]: The rounds loaded, as pictures, in the client's own order and WITHOUT their counts: a row is a glance, and a figure under every box would cost it twice the height. The battle's own panel carries the counts.
      - `name` string, required: AP, APCR, HEAT or HE, in the reader's language.
      - `image` string, required
    - `fieldMods` LoadoutSlot[]: The field modifications this vehicle carried, as pictures, in the tree's own order so two players on one tank can be compared position by position. Present far more often than the fitted loadout: a recording carries these for everyone who has any, about twelve of the thirty.
      - `name` string, nullable, required: The item's name in the reader's language, or null for a free slot. Here so a preview box can carry a tooltip: ten unlabelled pictures say very little. It is why this endpoint is privately cached rather than shared.
      - `filled` boolean, required: Whether the slot is occupied. Said outright because a row carries no names to infer it from, and because a slot filled with something no catalogue here can picture must not read as an empty one.
      - `image` string, nullable, required: The item's picture, or null where Wargaming publishes none.
      - `overlay` string, nullable, required: The grade badge drawn in the corner, which is what tells a Bounty device from an ordinary one: the picture underneath is the same.
      - `categories` string[]: The Equipment 2.0 categories the game dots the box with.
    - `players` number, required: Accounts the battle named, bots excluded.
    - `reporters` number, required: How many clients reported this battle. Two means two of our players were in it.
    - `personal` BattleEconomy, required: Credits, experience and bonds as the game's own Detailed Report breaks them down. Every field is absent when it is zero.
      - `creditsBase` number
      - `creditsBooster` number
      - `creditsEvent` number
      - `creditsOrder` number
      - `creditsPenalty` number
      - `creditsCompensation` number
      - `creditsSubtotal` number
      - `repairCost` number
      - `ammoCost` number
      - `suppliesCost` number
      - `credits` number
      - `xpBase` number
      - `xpBooster` number
      - `xpEvent` number
      - `xpPremiumVehicle` number
      - `xpPenalty` number
      - `xp` number
      - `freeXp` number
      - `crewXp` number
      - `bonds` number
      - `bondsBase` number
      - `premium` boolean

---

[API](https://skmtc.dev/unicum/apis/unicum-gg-api.md) · [All operations](https://skmtc.dev/unicum/apis/unicum-gg-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unicum/apis/unicum-gg-api/revisions/7a7d79a26001?raw)