Player stats v2

GET

/api/v2/player/{query}

Player StatsPremiumv2

Maintainer:Alastor

This endpoint retrieves player data for a specific player identified by uid or username.

IMPORTANT: Searching player stats by username is a new feature and is not always reliable. Searching player stats by player uid is more stable.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://marvelrivalsapi.com/api/v2/player/?season' \
--header 'x-api-key;'

Response Example

200 - Success

{
    "uid": 543511984,
    "name": "ToernB",
    "updates": {
        "info_update_time": "5/7/2025, 3:29:57 PM",
        "last_history_update": "7/22/2025, 7:32:54 AM",
        "last_inserted_match": "7/22/2025, 6:50:22 AM",
        "last_update_request": "7/23/2025, 10:03:05 AM"
    },
    "player": {
        "uid": 543511984,
        "level": "43",
        "name": "ToernB",
        "icon": {
            "player_icon_id": "31027204",
            "player_icon": "/players/heads/player_head_31027204.png",
            "banner": "/premium/nameplates/31027204_banner.webp?expires=1753283659&signature=4f72c4c5b018f903825681bd73fc93313b4a24840fa7d3d5023edefd52587393"
        },
        "team": {
            "club_team_id": "934_80",
            "club_team_mini_name": "TWOFID",
            "club_team_type": "0"
        },
        "info": {
            "completed_achievements": "102",
            "login_os": "PC",
            "rank_game_season": {
                "1001001": {
                    "rank_game_id": 1,
                    "level": 10,
                    "rank_score": 3894.3651498707495,
                    "max_level": 10,
                    "max_rank_score": 3999.657859194941,
                    "update_time": 1736452160,
                    "win_count": 96,
                    "protect_score": 0,
                    "diff_score": -11.9277523497949
                },
                "1001002": {
                    "rank_game_id": 2,
                    "level": 11,
                    "rank_score": 4007.0633661602137,
                    "max_level": 12,
                    "max_rank_score": 4111.801296371733,
                    "update_time": 1739993667,
                    "win_count": 112,
                    "protect_score": 0,
                    "diff_score": -21.95033149810024
                },
                "1001003": {
                    "rank_game_id": 3,
                    "level": 13,
                    "rank_score": 4229.917649646161,
                    "max_level": 13,
                    "max_rank_score": 4229.917649646161,
                    "update_time": 1742684552,
                    "win_count": 9,
                    "protect_score": 0,
                    "diff_score": 33.70900847638222
                },
                "1001004": {
                    "rank_game_id": 4,
                    "level": 8,
                    "rank_score": 3680.757168414914,
                    "max_level": 8,
                    "max_rank_score": 3738.8533679365632,
                    "update_time": 1747238399,
                    "win_count": 29,
                    "protect_score": 0,
                    "diff_score": -21.507109301622677
                },
                "1001005": {
                    "rank_game_id": 5,
                    "level": 7,
                    "rank_score": 3645.419398799876,
                    "max_level": 8,
                    "max_rank_score": 3758.8646823447457,
                    "update_time": 1751639090,
                    "win_count": 8,
                    "protect_score": 2,
                    "diff_score": -22.433479474959313
                },
                "1001006": {
                    "rank_game_id": 6,
                    "level": 5,
                    "rank_score": 3440.2259335209114,
                    "max_level": 5,
                    "max_rank_score": 3441.7012746847704,
                    "update_time": 1753182074,
                    "win_count": 20,
                    "protect_score": 3,
                    "diff_score": 32.19930621460708
                }
            }
        },
        "rank": {
            "rank": "Silver II",
            "score": "3,440",
            "unit": "RS",
            "icon": "/classes/silver.png",
            "color": "#7B9196",
            "peak_rank": {
                "rank": "Silver II",
                "score": "3,441",
                "unit": "RS",
                "icon": "/classes/silver.png",
                "color": "#7B9196"
            }
        }
    },
    "isPrivate": false,
    "overall_stats": {
        "total_matches": 55,
        "total_wins": {
            "wins": 20,
            "percentile_raw": 22,
            "percentile": "Bottom 22.0%",
            "win_percentage": {
                "percentile_raw": 36.4,
                "percentile": 1,
                "placement": "Bottom 1.0%"
            }
        },
        "total_play_time": {
            "time_played": 34780.11118102074,
            "playtime": "9h 39m 40s"
        },
        "per_minute": {
            "total_damage_per_minute": 1224,
            "total_damage_taken_per_minute": 922,
            "total_healing_per_minute": 328
        },
        "overall_kd": 1.8930131004366813,
        "overall_kda": {
            "kda": 2.47,
            "percentile_raw": 2,

Request

Path Params

query

string

required

The unique identifier of the player (could be uid or username).

Example:

player1234

Query Params

season

integer

optional

The season number for which the stats are retrieved (defaults to season 1).

Example:

Header Params

x-api-key

string

required

The API key for authorization. It is necessary to provide a valid API key to access the data.

Example:

your-api-key-here

Responses

🟢200OK

application/json

Successful response with player data

Body

uid

integer

required

The unique identifier for the player.

name

string

required

The player's name.

updates

object

required

Information about the player's updates.

info_update_time

string

required

last_history_update

string

required

last_inserted_match

string

required

last_update_request

string

required

player

object

required

The processed player data.

uid

integer

required

level

string

required

name

string

required

icon

object

required

team

object

required

info

object

required

rank

object

required

player_id

string

optional

The player ID.

Example:

player1234

nickname

string

optional

The player's nickname.

Example:

Player One

isPrivate

boolean

optional

Whether the player's profile is private.

Example:

false

isPrivate

boolean

required

overall_stats

object

required

The overall statistics of the player.

total_matches

integer

required

total_wins

object

required

total_play_time

object

required

per_minute

object

required

overall_kd

number

required

overall_kda

object

required

total_mvps

object

required

total_svps

object

required

total_kills

object

required

total_deaths

object

required

total_assists

object

required

total_damage

object

required

total_healing

object

required

total_damage_taken

object

required

max_kill_streak

object

required

roles_played

object

required

ranked

object

required

unranked

object

required

match_history

array [object {19}]

required

List of the player's match history.

match_uid

string

required

map_id

integer

required

map_thumbnail

string

required

duration

number

required

season

integer

required

winner_side

integer

required

mvp_uid

integer

required

svp_uid

integer

required

match_time_stamp

integer

required

play_mode_id

integer

required

game_mode_id

integer

required

score_info

object

required

player_performance

object

required

match_id

string

optional

The unique identifier for the match.

Example:

match123

date

string

optional

The date the match was played.

Example:

2024-02-10T15:30:00Z

result

string

optional

The result of the match (e.g., win, loss).

Example:

win

kills

integer

optional

The number of kills made by the player in the match.

Example:

deaths

integer

optional

The number of deaths the player had in the match.

Example:

assists

integer

optional

The number of assists made by the player in the match.

Example:

rank_history

array [object {6}]

required

List of the player's rank history.

match_time_stamp

integer

required

level_progression

object

required

score_progression

object

required

season

integer

optional

The season number.

Example:

rank

string

optional

The player's rank in the season.

Example:

Gold

points

integer

optional

The points the player had in the season.

Example:

1500

hero_matchups

array [object {7}]

required

The list of hero matchups for the player.

hero_id

integer

required

The hero's unique ID.

hero_name

string

required

hero_class

string

required

hero_thumbnail

string

required

matches

integer

required

wins

integer

required

win_rate

string

required

The player's win rate with this hero.

team_mates

array [object {6}]

required

The player's teammates in recent matches.

player_info

object

required

matches

integer

required

wins

integer

required

win_rate

string

required

teammate_id

string

optional

The unique ID of the teammate.

Example:

player5678

nickname

string

optional

The teammate's nickname.

Example:

Teammate One

heroes_ranked

array [object {15}]

required

The player's ranked heroes.

hero_id

integer

required

hero_name

string

required

hero_thumbnail

string

required

matches

integer

required

wins

integer

required

mvp

integer

required

svp

integer

required

kills

integer

required

deaths

integer

required

assists

integer

required

play_time

number

required

damage

number | integer

required

heal

integer | number

required

damage_taken

number | integer

required

main_attack

object

required

heroes_unranked

array[string]

required

The player's unranked heroes.

maps

array [object {8}]

required

Map statistics for the player.

map_id

integer

required

map_thumbnail

string

required

matches

integer

required

wins

integer

required

kills

integer

required

deaths

integer

required

assists

integer

required

play_time

number

required

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🔴500Server Error

Modified at 2025-07-24 14:17:00

Player stats

Update player