Match History v2

GET https://marvelrivalsapi.com/api/v2/player/:query/match-history

This endpoint retrieves the match history of a player based on their unique identifier (UID) or username. It allows filtering by season, game mode, and pagination (with page and limit).

Headers

Name	Value
Content-Type	application/json
x-api-key*	YOUR API KEY

Query Parameters

Name	Type	Required	Description
query*	string	✔️	The unique identifier of the player (could be uid or username).
season	integer	❌	The season to retrieve match history for. Defaults to current season
page	integer	❌	The page number for pagination. Defaults to 1 if not specified.
limit	integer	❌	The number of matches per page. Defaults to 40 if not specified.
skip	integer	❌	The number of matches to skip (pagination). Defaults to 20.
game_mode	integer	❌	The game mode to filter matches by. Defaults to 0.
timestamp	integer	❌	Filter matches by timestamp. Only includes matches after the given timestamp.

Example Requests

cURL

curl -X GET "https://marvelrivalsapi.com/api/v2/player/Sypeh/match-history"
     -H "x-api-key: YOUR_API_KEY"

Node.js

const axios = require("axios");

try {
    const response = await axios.get("https://marvelrivalsapi.com/api/v2/player/Sypeh/match-history", {
        headers: {
            "x-api-key": "YOUR_API_KEY"
        }
    });
    console.log(response.data);
} catch (error) {
    console.error("Error fetching balances:", error.response ? error.response.data : error.message);
}

Python

import requests

url = "https://marvelrivalsapi.com/api/v2/player/Sypeh/match-history"
headers = {
    "x-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error {response.status_code}: {response.text}")

Java

import java.net.http.*;
import java.net.URI;
import java.io.IOException;

public class ApiClient {
    public static void main(String[] args) {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://marvelrivalsapi.com/api/v2/player/Sypeh/match-history"))
            .header("x-api-key", "YOUR_API_KEY")
            .GET()
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
        }
    }
}

Response

200

{
    "match_history": [
        {
            "match_map_id": 1217,
            "map_thumbnail": "/rivals/maps/map_1217.png",
            "match_play_duration": "8m 59s",
            "match_season": "1.5",
            "match_uid": "4890883_1741845325_1565_11001_10",
            "match_winner_side": 0,
            "mvp_uid": 445990150,
            "svp_uid": 538661026,
            "score_info": null,
            "match_time_stamp": 1741845957,
            "play_mode_id": 0,
            "game_mode_id": 1,
            "match_player": {
                "assists": 5,
                "kills": 8,
                "deaths": 9,
                "is_win": {
                    "score": 0,
                    "is_win": false
                },
                "disconnected": false,
                "player_uid": 632183034,
                "camp": 1,
                "score_info": {
                    "add_score": -35.36539720815472,
                    "level": 1,
                    "new_level": 1,
                    "new_score": 3194.0073244099885
                },
                "player_hero": {
                    "hero_id": 1047,
                    "hero_name": "jeff the land shark",
                    "hero_type": "/heroes/transformations/jeff-the-land-shark-headbig-0.webp",
                    "kills": 8,
                    "deaths": 9,
                    "assists": 5,
                    "play_time": {
                        "raw": 539.3805547300726,
                        "formatted": "8m 59s"
                    },
                    "total_hero_damage": 6852.4064083099365,
                    "total_damage_taken": 6883.935603141785,
                    "total_hero_heal": 8338.68634223938
                }
            }
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 40,
        "total_matches": 185,
        "total_pages": 5,
        "has_more": true
    }
}

400

{
  "error": true,
  "message": "Invalid query parameter (e.g., missing player UID or username).",
  "status": 400
}

401

{
  "error": true,
  "message": "Invalid or missing API key.",
  "status": 401
}

404

{
  "error": true,
  "message": "Player not found or match data unavailable for the specified query",
  "status": 404
}

500

{
  "error": true,
  "message": "An error occurred while fetching data.",
  "status": 500
}

Response Field Descriptions

Field	Type	Description
match_history	Array	List of match history entries.
match_history.match_map_id	Number	ID of the map played in the match (e.g., 1217).
match_history.map_thumbnail	String	URL or path to the map thumbnail (e.g., "/rivals/maps/map_1217.png").
match_history.match_play_duration	String	Duration of the match (e.g., "8m 59s").
match_history.match_season	String	Season of the match (e.g., "1.5").
match_history.match_uid	String	Unique identifier for the match (e.g., "4890883_1741845325_1565_11001_10").
match_history.match_winner_side	Number	Side that won the match (e.g., 0 for team A, 1 for team B).
match_history.mvp_uid	Number	Unique identifier for the MVP player (e.g., 445990150).
match_history.svp_uid	Number	Unique identifier for the SVP player (e.g., 538661026).
match_history.score_info	Null	Additional score-related data (e.g., null).
match_history.match_time_stamp	Number	Timestamp of the match (e.g., 1741845957).
match_history.play_mode_id	Number	ID of the play mode used in the match (e.g., 0).
match_history.game_mode_id	Number	ID of the game mode used in the match (e.g., 1).
match_history.match_player	Object	Information about a specific player in the match.
match_history.match_player.assists	Number	The number of assists by the player in the match (e.g., 5).
match_history.match_player.kills	Number	The number of kills by the player in the match (e.g., 8).
match_history.match_player.deaths	Number	The number of deaths by the player in the match (e.g., 9).
match_history.match_player.is_win	Object	Whether the player won the match and the score details.
match_history.match_player.is_win.score	Number	Score of the player in the match (e.g., 0).
match_history.match_player.is_win.is_win	Boolean	Whether the player won the match (e.g., false).
match_history.match_player.disconnected	Boolean	Whether the player disconnected during the match (e.g., false).
match_history.match_player.player_uid	Number	Unique identifier for the player (e.g., 632183034).
match_history.match_player.camp	Number	The camp the player was on (e.g., 1).
match_history.match_player.score_info	Object	Additional score-related info for the player.
match_history.match_player.score_info.add_score	Number	Additional score added to the player (e.g., -35.36539720815472).
match_history.match_player.score_info.level	Number	Level of the player during the match (e.g., 1).
match_history.match_player.score_info.new_level	Number	New level of the player after the match (e.g., 1).
match_history.match_player.score_info.new_score	Number	New score of the player after the match (e.g., 3194.0073244099885).
match_history.match_player.player_hero	Object	Information about the player's hero in the match.
match_history.match_player.player_hero.hero_id	Number	ID of the hero played by the player (e.g., 1047).
match_history.match_player.player_hero.hero_name	String	Name of the hero played by the player (e.g., "jeff the land shark").
match_history.match_player.player_hero.hero_type	String	Type of the hero (e.g., "/heroes/transformations/jeff-the-land-shark-headbig-0.webp").
match_history.match_player.player_hero.kills	Number	The number of kills by the hero in the match (e.g., 8).
match_history.match_player.player_hero.deaths	Number	The number of deaths by the hero in the match (e.g., 9).
match_history.match_player.player_hero.assists	Number	The number of assists by the hero in the match (e.g., 5).
match_history.match_player.player_hero.play_time.raw	Number	Raw play time spent on the hero (e.g., 539.3805547300726).
match_history.match_player.player_hero.play_time.formatted	String	Formatted play time spent on the hero (e.g., "8m 59s").
match_history.match_player.player_hero.total_hero_damage	Number	Total hero damage dealt by the hero (e.g., 6852.4064083099365).
match_history.match_player.player_hero.total_damage_taken	Number	Total damage taken by the hero (e.g., 6883.935603141785).
match_history.match_player.player_hero.total_hero_heal	Number	Total healing done by the hero (e.g., 8338.68634223938).
pagination	Object	Pagination details for the match history.
pagination.page	Number	Current page number (e.g., 1).
pagination.limit	Number	Number of matches per page (e.g., 40).
pagination.total_matches	Number	Total number of matches (e.g., 185).
pagination.total_pages	Number	Total number of pages (e.g., 5).
pagination.has_more	Boolean	Whether there are more pages of matches (e.g., true).