Riot Games API Documentation

# Match-v5 API **Routing Information:** The AMERICAS routing value serves NA, BR, LAN and LAS. The ASIA routing value serves KR and JP. The EUROPE routing value serves EUNE, EUW, ME1, TR and RU. The SEA routing value serves OCE, SG2, TW2 and VN2. --- ## Endpoint: GET /lol/match/v5/matches/by-puuid/{puuid}/ids **Description:** Get a list of match ids by puuid ### Path Parameters - **puuid** (required, String) ### Query Parameters - **startTime** (optional, long): Epoch timestamp in seconds. The matchlist started storing timestamps on June 16th, 2021. Any matches played before June 16th, 2021 won't be included in the results if the startTime filter is set. - **endTime** (optional, long): Epoch timestamp in seconds. - **queue** (optional, int): Filter the list of match ids by a specific queue id. This filter is mutually inclusive of the type filter meaning any match ids returned must match both the queue and type filters. - **type** (optional, string): Filter the list of match ids by the type of match. This filter is mutually inclusive of the queue filter meaning any match ids returned must match both the queue and type filters. Legal values: ranked, normal, tourney, tutorial - **start** (optional, int): Defaults to 0. Start index. - **count** (optional, int): Defaults to 20. Valid values: 0 to 100. Number of match ids to return. ### Response: List[string] ### Response Errors | HTTP Status Code | Reason | |------------------|--------| | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Data not found | | 405 | Method not allowed | | 415 | Unsupported media type | | 429 | Rate limit exceeded | | 500 | Internal server error | | 502 | Bad gateway | | 503 | Service unavailable | | 504 | Gateway timeout | ### Supported Regions AMERICAS, ASIA, EUROPE, SEA --- ## Endpoint: GET /lol/match/v5/matches/{matchId} **Description:** Get a match by match id ### Path Parameters - **matchId** (required, String) ### Response: MatchDto #### MatchDto | Field | Data Type | Description | |-------|-----------|-------------| | metadata | MetadataDto | Match metadata. | | info | InfoDto | Match info. | #### MetadataDto | Field | Data Type | Description | |-------|-----------|-------------| | dataVersion | string | Match data version. | | matchId | string | Match id. | | participants | List[string] | A list of participant PUUIDs. | #### InfoDto | Field | Data Type | Description | |-------|-----------|-------------| | endOfGameResult | string | Refer to indicate if the game ended in termination. | | gameCreation | long | Unix timestamp for when the game is created on the game server (i.e., the loading screen). | | gameDuration | long | Prior to patch 11.20, this field returns the game length in milliseconds calculated from gameEndTimestamp - gameStartTimestamp. Post patch 11.20, this field returns the max timePlayed of any participant in the game in seconds, which makes the behavior of this field consistent with that of match-v4. The best way to handling the change in this field is to treat the value as milliseconds if the gameEndTimestamp field isn't in the response and to treat the value as seconds if gameEndTimestamp is in the response. | | gameEndTimestamp | long | Unix timestamp for when match ends on the game server. This timestamp can occasionally be significantly longer than when the match "ends". The most reliable way of determining the timestamp for the end of the match would be to add the max time played of any participant to the gameStartTimestamp. This field was added to match-v5 in patch 11.20 on Oct 5th, 2021. | | gameId | long | | | gameMode | string | Refer to the Game Constants documentation. | | gameName | string | | | gameStartTimestamp | long | Unix timestamp for when match starts on the game server. | | gameType | string | | | gameVersion | string | The first two parts can be used to determine the patch a game was played on. | | mapId | int | Refer to the Game Constants documentation. | | participants | List[ParticipantDto] | | | platformId | string | Platform where the match was played. | | queueId | int | Refer to the Game Constants documentation. | | teams | List[TeamDto] | | | tournamentCode | string | Tournament code used to generate the match. This field was added to match-v5 in patch 11.13 on June 23rd, 2021. | #### ParticipantDto | Field | Data Type | Description | |-------|-----------|-------------| | allInPings | int | Yellow crossed swords | | assistMePings | int | Green flag | | assists | int | | | baronKills | int | | | bountyLevel | int | | | champExperience | int | | | champLevel | int | | | championId | int | Prior to patch 11.4, on Feb 18th, 2021, this field returned invalid championIds. We recommend determining the champion based on the championName field for matches played prior to patch 11.4. | | championName | string | | | commandPings | int | Blue generic ping (ALT+click) | | championTransform | int | This field is currently only utilized for Kayn's transformations. (Legal values: 0 - None, 1 - Slayer, 2 - Assassin) | | consumablesPurchased | int | | | challenges | ChallengesDto | | | damageDealtToBuildings | int | | | damageDealtToObjectives | int | | | damageDealtToTurrets | int | | | damageSelfMitigated | int | | | deaths | int | | | detectorWardsPlaced | int | | | doubleKills | int | | | dragonKills | int | | | eligibleForProgression | boolean | | | enemyMissingPings | int | Yellow questionmark | | enemyVisionPings | int | Red eyeball | | firstBloodAssist | boolean | | | firstBloodKill | boolean | | | firstTowerAssist | boolean | | | firstTowerKill | boolean | | | gameEndedInEarlySurrender | boolean | This is an offshoot of the OneStone challenge. The code checks if a spell with the same instance ID does the final point of damage to at least 2 Champions. It doesn't matter if they're enemies, but you cannot hurt your friends. | | gameEndedInSurrender | boolean | | | holdPings | int | | | getBackPings | int | Yellow circle with horizontal line | | goldEarned | int | | | goldSpent | int | | | individualPosition | string | Both individualPosition and teamPosition are computed by the game server and are different versions of the most likely position played by a player. The individualPosition is the best guess for which position the player actually played in isolation of anything else. The teamPosition is the best guess for which position the player actually played if we add the constraint that each team must have one top player, one jungle, one middle, etc. Generally the recommendation is to use the teamPosition field over the individualPosition field. | | inhibitorKills | int | | | inhibitorTakedowns | int | | | inhibitorsLost | int | | | item0 | int | | | item1 | int | | | item2 | int | | | item3 | int | | | item4 | int | | | item5 | int | | | item6 | int | | | itemsPurchased | int | | | killingSprees | int | | | kills | int | | | lane | string | | | largestCriticalStrike | int | | | largestKillingSpree | int | | | largestMultiKill | int | | | longestTimeSpentLiving | int | | | magicDamageDealt | int | | | magicDamageDealtToChampions | int | | | magicDamageTaken | int | | | missions | MissionsDto | | | neutralMinionsKilled | int | neutralMinionsKilled = mNeutralMinionsKilled, which is incremented on kills of kPet and kJungleMonster | | needVisionPings | int | Green ward | | nexusKills | int | | | nexusTakedowns | int | | | nexusLost | int | | | objectivesStolen | int | | | objectivesStolenAssists | int | | | onMyWayPings | int | Blue arrow pointing at ground | | participantId | int | | | playerScore0 | int | | | playerScore1 | int | | | playerScore2 | int | | | playerScore3 | int | | | playerScore4 | int | | | playerScore5 | int | | | playerScore6 | int | | | playerScore7 | int | | | playerScore8 | int | | | playerScore9 | int | | | playerScore10 | int | | | playerScore11 | int | | | pentaKills | int | | | perks | PerksDto | | | physicalDamageDealt | int | | | physicalDamageDealtToChampions | int | | | physicalDamageTaken | int | | | placement | int | | | playerAugment1 | int | | | playerAugment2 | int | | | playerAugment3 | int | | | playerAugment4 | int | | | playerSubteamId | int | | | pushPings | int | Green minion | | profileIcon | int | | | puuid | string | | | quadraKills | int | | | riotIdGameName | string | | | riotIdTagline | string | | | role | string | | | sightWardsBoughtInGame | int | | | spell1Casts | int | | | spell2Casts | int | | | spell3Casts | int | | | spell4Casts | int | | | subteamPlacement | int | | | summoner1Casts | int | | | summoner1Id | int | | | summoner2Casts | int | | | summoner2Id | int | | | summonerId | string | | | summonerLevel | int | | | summonerName | string | | | teamEarlySurrendered | boolean | | | teamId | int | | | teamPosition | string | Both individualPosition and teamPosition are computed by the game server and are different versions of the most likely position played by a player. The individualPosition is the best guess for which position the player actually played in isolation of anything else. The teamPosition is the best guess for which position the player actually played if we add the constraint that each team must have one top player, one jungle, one middle, etc. Generally the recommendation is to use the teamPosition field over the individualPosition field. | | timeCCingOthers | int | | | timePlayed | int | | | totalAllyJungleMinionsKilled | int | | | totalDamageDealt | int | | | totalDamageDealtToChampions | int | | | totalDamageShieldedOnTeammates | int | | | totalDamageTaken | int | | | totalEnemyJungleMinionsKilled | int | | | totalHeal | int | Whenever positive health is applied (which translates to all heals in the game but not things like regeneration), totalHeal is incremented by the amount of health received. This includes healing enemies, jungle monsters, yourself, etc | | totalHealsOnTeammates | int | Whenever positive health is applied (which translates to all heals in the game but not things like regeneration), totalHealsOnTeammates is incremented by the amount of health received. This is post modified, so if you heal someone missing 5 health for 100 you will get +5 totalHealsOnTeammates | | totalMinionsKilled | int | totalMillionsKilled = mMinionsKilled, which is only incremented on kills of kTeamMinion, kMeleeLaneMinion, kSuperLaneMinion, kRangedLaneMinion and kSiegeLaneMinion | | totalTimeCCDealt | int | | | totalTimeSpentDead | int | | | totalUnitsHealed | int | | | tripleKills | int | | | trueDamageDealt | int | | | trueDamageDealtToChampions | int | | | trueDamageTaken | int | | | turretKills | int | | | turretTakedowns | int | | | turretsLost | int | | | unrealKills | int | | | visionScore | int | | | visionClearedPings | int | | | visionWardsBoughtInGame | int | | | wardsKilled | int | | | wardsPlaced | int | | | win | boolean | | #### ChallengesDto Challenges DTO | Field | Data Type | Description | |-------|-----------|-------------| | 12AssistStreakCount | int | | | baronBuffGoldAdvantageOverThreshold | int | | | controlWardTimeCoverageInRiverOrEnemyHalf | float | | | earliestBaron | int | | | earliestDragonTakedown | int | | | earliestElderDragon | int | | | earlyLaningPhaseGoldExpAdvantage | int | | | fasterSupportQuestCompletion | int | | | fastestLegendary | int | | | hadAfkTeammate | int | | | highestChampionDamage | int | | | highestCrowdControlScore | int | | | highestWardKills | int | | | junglerKillsEarlyJungle | int | | | killsOnLanersEarlyJungleAsJungler | int | | | laningPhaseGoldExpAdvantage | int | | | legendaryCount | int | | | maxCsAdvantageOnLaneOpponent | float | | | maxLevelLeadLaneOpponent | int | | | mostWardsDestroyedOneSweeper | int | | | mythicItemUsed | int | | | playedChampSelectPosition | int | | | soloTurretsLategame | int | | | takedownsFirst25Minutes | int | | | teleportTakedowns | int | | | thirdInhibitorDestroyedTime | int | | | threeWardsOneSweeperCount | int | | | visionScoreAdvantageLaneOpponent | float | | | InfernalScalePickup | int | | | fistBumpParticipation | int | | | voidMonsterKill | int | | | abilityUses | int | | | acesBefore15Minutes | int | | | alliedJungleMonsterKills | float | | | baronTakedowns | int | | | blastConeOppositeOpponentCount | int | | | bountyGold | int | | | buffsStolen | int | | | completeSupportQuestInTime | int | | | controlWardsPlaced | int | | | damagePerMinute | float | | | damageTakenOnTeamPercentage | float | | | dancedWithRiftHerald | int | | | deathsByEnemyChamps | int | | | dodgeSkillShotsSmallWindow | int | | | doubleAces | int | | | dragonTakedowns | int | | | legendaryItemUsed | List[int] | | | effectiveHealAndShielding | float | | | elderDragonKillsWithOpposingSoul | int | | | elderDragonMultikills | int | | | enemyChampionImmobilizations | int | | | enemyJungleMonsterKills | float | | | epicMonsterKillsNearEnemyJungler | int | | | epicMonsterKillsWithin30SecondsOfSpawn | int | | | epicMonsterSteals | int | | | epicMonsterStolenWithoutSmite | int | | | firstTurretKilled | int | | | firstTurretKilledTime | float | | | flawlessAces | int | | | fullTeamTakedown | int | | | gameLength | float | | | getTakedownsInAllLanesEarlyJungleAsLaner | int | | | goldPerMinute | float | | | hadOpenNexus | int | | | immobilizeAndKillWithAlly | int | | | initialBuffCount | int | | | initialCrabCount | int | | | jungleCsBefore10Minutes | float | | | junglerTakedownsNearDamagedEpicMonster | int | | | kda | float | | | killAfterHiddenWithAlly | int | | | killedChampTookFullTeamDamageSurvived | int | | | killingSprees | int | | | killParticipation | float | | | killsNearEnemyTurret | int | | | killsOnOtherLanesEarlyJungleAsLaner | int | | | killsOnRecentlyHealedByAramPack | int | | | killsUnderOwnTurret | int | | | killsWithHelpFromEpicMonster | int | | | knockEnemyIntoTeamAndKill | int | | | kTurretsDestroyedBeforePlatesFall | int | | | landSkillShotsEarlyGame | int | | | laneMinionsFirst10Minutes | int | | | lostAnInhibitor | int | | | maxKillDeficit | int | | | mejaisFullStackInTime | int | | | moreEnemyJungleThanOpponent | float | | | multiKillOneSpell | int | This is an offshoot of the OneStone challenge. The code checks if a spell with the same instance ID does the final point of damage to at least 2 Champions. It doesn't matter if they're enemies, but you cannot hurt your friends. | | multikills | int | | | multikillsAfterAggressiveFlash | int | | | multiTurretRiftHeraldCount | int | | | outerTurretExecutesBefore10Minutes | int | | | outnumberedKills | int | | | outnumberedNexusKill | int | | | perfectDragonSoulsTaken | int | | | perfectGame | int | | | pickKillWithAlly | int | | | poroExplosions | int | | | quickCleanse | int | | | quickFirstTurret | int | | | quickSoloKills | int | | | riftHeraldTakedowns | int | | | saveAllyFromDeath | int | | | scuttleCrabKills | int | | | shortestTimeToAceFromFirstTakedown | float | | | skillshotsDodged | int | | | skillshotsHit | int | | | snowballsHit | int | | | soloBaronKills | int | | | SWARM_DefeatAatrox | int | | | SWARM_DefeatBriar | int | | | SWARM_DefeatMiniBosses | int | | | SWARM_EvolveWeapon | int | | | SWARM_Have3Passives | int | | | SWARM_KillEnemy | int | | | SWARM_PickupGold | float | | | SWARM_ReachLevel50 | int | | | SWARM_Survive15Min | int | | | SWARM_WinWith5EvolvedWeapons | int | | | soloKills | int | | | stealthWardsPlaced | int | | | survivedSingleDigitHpCount | int | | | survivedThreeImmobilizesInFight | int | | | takedownOnFirstTurret | int | | | takedowns | int | | | takedownsAfterGainingLevelAdvantage | int | | | takedownsBeforeJungleMinionSpawn | int | | | takedownsFirstXMinutes | int | | | takedownsInAlcove | int | | | takedownsInEnemyFountain | int | | | teamBaronKills | int | | | teamDamagePercentage | float | | | teamElderDragonKills | int | | | teamRiftHeraldKills | int | | | tookLargeDamageSurvived | int | | | turretPlatesTaken | int | | | turretsTakenWithRiftHerald | int | Any player who damages a tower that is destroyed within 30 seconds of a Rift Herald charge will receive credit. A player who does not damage the tower will not receive credit. | | turretTakedowns | int | | | twentyMinionsIn3SecondsCount | int | | | twoWardsOneSweeperCount | int | | | unseenRecalls | int | | | visionScorePerMinute | float | | | wardsGuarded | int | | | wardTakedowns | int | | | wardTakedownsBefore20M | int | | #### MissionsDto Missions DTO | Field | Data Type | Description | |-------|-----------|-------------| | playerScore0 | int | | | playerScore1 | int | | | playerScore2 | int | | | playerScore3 | int | | | playerScore4 | int | | | playerScore5 | int | | | playerScore6 | int | | | playerScore7 | int | | | playerScore8 | int | | | playerScore9 | int | | | playerScore10 | int | | | playerScore11 | int | | #### PerksDto | Field | Data Type | Description | |-------|-----------|-------------| | statPerks | PerkStatsDto | | | styles | List[PerkStyleDto] | | #### PerkStatsDto | Field | Data Type | Description | |-------|-----------|-------------| | defense | int | | | flex | int | | | offense | int | | #### PerkStyleDto | Field | Data Type | Description | |-------|-----------|-------------| | description | string | | | selections | List[PerkStyleSelectionDto] | | | style | int | | #### PerkStyleSelectionDto | Field | Data Type | Description | |-------|-----------|-------------| | perk | int | | | var1 | int | | | var2 | int | | | var3 | int | | #### TeamDto | Field | Data Type | Description | |-------|-----------|-------------| | bans | List[BanDto] | | | objectives | ObjectivesDto | | | teamId | int | | | win | boolean | | #### BanDto | Field | Data Type | Description | |-------|-----------|-------------| | championId | int | | | pickTurn | int | | #### ObjectivesDto | Field | Data Type | Description | |-------|-----------|-------------| | baron | ObjectiveDto | | | champion | ObjectiveDto | | | dragon | ObjectiveDto | | | horde | ObjectiveDto | | | inhibitor | ObjectiveDto | | | riftHerald | ObjectiveDto | | | tower | ObjectiveDto | | #### ObjectiveDto | Field | Data Type | Description | |-------|-----------|-------------| | first | boolean | | | kills | int | | ### Response Errors | HTTP Status Code | Reason | |------------------|--------| | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Data not found | | 405 | Method not allowed | | 415 | Unsupported media type | | 429 | Rate limit exceeded | | 500 | Internal server error | | 502 | Bad gateway | | 503 | Service unavailable | | 504 | Gateway timeout | ### Supported Regions AMERICAS, ASIA, EUROPE, SEA --- ## Endpoint: GET /lol/match/v5/matches/{matchId}/timeline **Description:** Get a match timeline by match id ### Path Parameters - **matchId** (required, String) ### Response: TimelineDto #### TimelineDto | Field | Data Type | Description | |-------|-----------|-------------| | metadata | MetadataTimeLineDto | Match metadata. | | info | InfoTimeLineDto | Match info. | #### MetadataTimeLineDto | Field | Data Type | Description | |-------|-----------|-------------| | dataVersion | string | Match data version. | | matchId | string | Match id. | | participants | List[string] | A list of participant PUUIDs. | #### InfoTimeLineDto | Field | Data Type | Description | |-------|-----------|-------------| | endOfGameResult | string | Refer to indicate if the game ended in termination. | | frameInterval | long | | | gameId | long | | | participants | List[ParticipantTimeLineDto] | | | frames | List[FramesTimeLineDto] | | #### ParticipantTimeLineDto | Field | Data Type | Description | |-------|-----------|-------------| | participantId | int | | | puuid | string | | #### FramesTimeLineDto | Field | Data Type | Description | |-------|-----------|-------------| | events | List[EventsTimeLineDto] | | | participantFrames | ParticipantFramesDto | | | timestamp | int | | #### EventsTimeLineDto | Field | Data Type | Description | |-------|-----------|-------------| | timestamp | long | | | realTimestamp | long | | | type | string | | #### ParticipantFramesDto | Field | Data Type | Description | |-------|-----------|-------------| | 1-9 | ParticipantFrameDto | Key value mapping for each participant | #### ParticipantFrameDto | Field | Data Type | Description | |-------|-----------|-------------| | championStats | ChampionStatsDto | | | currentGold | int | | | damageStats | DamageStatsDto | | | goldPerSecond | int | | | jungleMinionsKilled | int | | | level | int | | | minionsKilled | int | | | participantId | int | | | position | PositionDto | | | timeEnemySpentControlled | int | | | totalGold | int | | | xp | int | | #### ChampionStatsDto | Field | Data Type | Description | |-------|-----------|-------------| | abilityHaste | int | | | abilityPower | int | | | armor | int | | | armorPen | int | | | armorPenPercent | int | | | attackDamage | int | | | attackSpeed | int | | | bonusArmorPenPercent | int | | | bonusMagicPenPercent | int | | | ccReduction | int | | | cooldownReduction | int | | | health | int | | | healthMax | int | | | healthRegen | int | | | lifesteal | int | | | magicPen | int | | | magicPenPercent | int | | | magicResist | int | | | movementSpeed | int | | | omnivamp | int | | | physicalVamp | int | | | power | int | | | powerMax | int | | | powerRegen | int | | | spellVamp | int | | #### DamageStatsDto | Field | Data Type | Description | |-------|-----------|-------------| | magicDamageDone | int | | | magicDamageDoneToChampions | int | | | magicDamageTaken | int | | | physicalDamageDone | int | | | physicalDamageDoneToChampions | int | | | physicalDamageTaken | int | | | totalDamageDone | int | | | totalDamageDoneToChampions | int | | | totalDamageTaken | int | | | trueDamageDone | int | | | trueDamageDoneToChampions | int | | | trueDamageTaken | int | | #### PositionDto | Field | Data Type | Description | |-------|-----------|-------------| | x | int | | | y | int | | ### Response Errors | HTTP Status Code | Reason | |------------------|--------| | 400 | Bad request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Data not found | | 405 | Method not allowed | | 415 | Unsupported media type | | 429 | Rate limit exceeded | | 500 | Internal server error | | 502 | Bad gateway | | 503 | Service unavailable | | 504 | Gateway timeout | ### Supported Regions AMERICAS, ASIA, EUROPE, SEA