DOCSEARCHbyAlgolia
Submit Docs

RetroAchievements API

website·Indexed 35 days ago

https://api-docs.retroachievements.org/

API documentation for accessing RetroAchievements data, including game metadata, achievement unlocks, leaderboards, user progress, and system hashes. Includes guides for getting started and standalones integration.

Tokens
24.9K
Snippets
175
Records
188
Agent score
58%

What's inside RetroAchievements

  1. Retrieve active set claims via HTTP API

    Use the API_GetActiveClaims.php endpoint to retrieve information about all active set claims (maximum of 1000). This request requires a web API key passed as a query parameter.
    GET https://retroachievements.org/API/API_GetActiveClaims.php?y=<your_web_api_key>

  2. Retrieve game progression and achievement unlock times

    The Game Progression endpoint retrieves information about the average time to unlock achievements in a specific game, targeted via its unique game ID. This includes median times to beat, complete, and master the game, as well as specific timing data for each achievement.
    GET https://retroachievements.org/API/API_GetGameProgression.php?y={webApiKey}&i={gameId}

  3. Retrieve a user's game rank and score via HTTP

    Use the API_GetUserGameRankAndScore.php endpoint to retrieve metadata about a user's performance and ranking for a specific game. You can identify the user by their username or their ULID. Note that usernames are not stable values (users can change them), so it is recommended to use the username initially to fetch a stable ULID for future requests.
    GET https://retroachievements.org/API/API_GetUserGameRankAndScore.php?y={YOUR_API_KEY}&u={USERNAME_OR_ULID}&g={GAME_ID}

  4. Retrieve user awards via HTTP GET

    Use the API_GetUserAwards.php endpoint to retrieve metadata about a target user's site awards. You can identify the user by their username or their ULID. Note that usernames are not stable identifiers as of 2025; it is recommended to use the username initially to fetch a stable ULID for future requests.
    GET https://retroachievements.org/API/API_GetUserAwards.php?u=USERNAME_OR_ULID&y=YOUR_WEB_API_KEY

  5. Retrieve extended game metadata via HTTP API

    Use the API_GetGameExtended.php endpoint to retrieve extended metadata about a game, including publisher, developer, genre, and a detailed list of achievements. The request requires a web API key and the target game ID.
    GET https://retroachievements.org/API/API_GetGameExtended.php?y={YOUR_API_KEY}&i={GAME_ID}

  6. Retrieve game info and user progress via HTTP

    Use the API_GetGameInfoAndUserProgress.php endpoint to get extended metadata about a game and a specific user's progress. You can identify the user by either their username or their ULID. Note that usernames are not stable (users can change them), so it is recommended to use the username initially to fetch a stable ULID for future requests.

    Endpoint: https://retroachievements.org/API/API_GetGameInfoAndUserProgress.php

    GET /API/API_GetGameInfoAndUserProgress.php?y={YOUR_API_KEY}&u={USERNAME_OR_ULID}&g={GAME_ID}

  7. Retrieve game high scores and mastery ranks

    Use the API_GetGameRankAndScore.php endpoint to retrieve metadata about the latest masters or the highest point earners for a specific game. The results are ordered based on the request type: for latest-masters, the first entry is the most recent mastery; for high-scores, the first entry is the first person to master the set.
    GET https://retroachievements.org/API/API_GetGameRankAndScore.php?y={webApiKey}&g={gameId}&t={type}

  8. Retrieve inactive achievement set development claims

    Use the API_GetClaims.php endpoint to retrieve information about up to 1000 achievement set development claims. You can filter these claims by their status: completed, dropped, or expired.
    GET https://retroachievements.org/API/API_GetClaims.php?y={YOUR_API_KEY}&k={CLAIM_KIND}

  9. Retrieve achievement ticket metadata by ID

    Use the API_GetTicketData endpoint to retrieve metadata information about a single achievement ticket using its unique ticket ID. This is useful for accessing details about reported achievement issues, including the achievement title, game ID, report state, and resolution details.
    GET https://retroachievements.org/API/API_GetTicketData.php?y=<your_web_api_key>&i=12345

  10. Retrieve the most recent achievement tickets via HTTP

    Use the API_GetTicketData endpoint to retrieve metadata about the latest opened achievement tickets on RetroAchievements. This is useful for monitoring recent reports of achievements not triggering or other ticket-related issues.
    GET https://retroachievements.org/API/API_GetTicketData.php?y=<YOUR_API_KEY>&c=10&o=0

  11. Retrieve the current Achievement of the Week

    Use the API_GetAchievementOfTheWeek.php endpoint to retrieve comprehensive metadata about the current Achievement of the Week. The response includes details about the achievement, the associated game and console, the forum topic, and a list of users who have unlocked it.
    GET https://retroachievements.org/API/API_GetAchievementOfTheWeek.php?y=<your_web_api_key>

  12. Retrieve a Connect API token for standalone integrations

    To interact with the Connect API (dorequest.php), you must first obtain a secret token using your integration account's credentials. All requests to the Connect API MUST include a User-Agent header in the format: {Frontend/Standalone name}/{x.y.z Version} ({platform}) {Integration/x.y.z} {core information}.
    # Example request to get token
curl -H "User-Agent: HorizonXI/1.0.0 (Server)" "https://retroachievements.org/dorequest.php?u=YourUsername&p=YourPassword&r=login2"