Skip to main content

​
Stored Matches

This guide explains how stored match history is built, paginated, and why it may be incomplete compared with Riot’s full history.

​
Endpoints

Both endpoints return the same response shape. The Riot ID route resolves the account first; the PUUID route uses the supplied player UUID.

​
Query parameters

Example:
Results are sorted newest first by match start time. page and size are applied to the stored database records after the API has attempted to fetch the recent match IDs from Riot.

​
Response shape

results.total, results.returned, before, and after refer to the stored records matching the request. teams.red and teams.blue are the stored round-win values; they are not team IDs.

​
Important completeness behavior

Stored matches are an accumulating materialized subset of Riot’s match history, not a pre-populated mirror of every match. When a stored-matches request runs, the API:
  1. Fetches the player’s recent match IDs from Riot’s competitive-updates history.
  2. Attempts to fetch each match’s full details.
  3. Stores successful match details in the match store and writes searchable metadata for the players, map, mode, season, and teams.
  4. Reads the response from the stored metadata collection, applying the requested filters and pagination.
The endpoint does not return a placeholder for a match that could not be fetched or stored. A match may be absent because Riot did not return usable details, the match is temporarily unavailable, storage failed or was simply never requested by any developer using this API. The fetch attempts run concurrently and their individual errors are not returned as per-item errors by this endpoint. As a result:
  • The list may have holes compared with Riot’s match history.
  • total is not the player’s total number of matches; it is the number currently stored that match the filters.
  • A page can change between requests as previously unavailable matches are successfully stored.
  • A successful fetch normally makes that match available to later stored-matches requests, subject to the same account, affinity, mode, and map filters.
Consumers should use meta.id and meta.started_at to identify and order matches, tolerate missing matches, and avoid assuming that page boundaries represent fixed positions in Riot’s complete history. If a complete or immediately live history is required, use the non-stored match-history endpoints instead and treat their full-match availability separately.