Skip to content

User Specific Games Progress

A call to this endpoint will retrieve a given user's progress on a given list of games, targeted by a list of game IDs.

WARNING

Unless you are explicitly wanting summary progress details for specific game IDs, the All Completion Progress endpoint will almost certainly be better-suited for your use case.

HTTP Request

GET

https://retroachievements.org/API/API_GetUserProgress.php?u=MaxMilyin&i=1,2,3

Query Parameters

NameRequired?Description
zYesYour username.
yYesYour web API key.
uYesThe target username.
iYesThe target game IDs, as a comma-separated value.

Client Library

ts
import { buildAuthorization, getUserProgress } from "@retroachievements/api";

// First, build your authorization object.
const username = "<your username on RA>";
const webApiKey = "<your web API key>";

const authorization = buildAuthorization({ username, webApiKey });

// Then, make the API call.
const userGamesProgress = await getUserProgress(authorization, {
  username: "MaxMilyin",
  gameIds: [1, 2, 3],
});
kotlin
val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserProgress.Response, ErrorResponse> = api.getUserProgress(
    username = "MaxMilyin",
    gameId = "1,2,3"
)

if (response is NetworkResponse.Success) {
    // handle the data
    val userProgress: GetUserProgress.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Response

json
{
  "1": {
    "NumPossibleAchievements": 23,
    "PossibleScore": 251,
    "NumAchieved": 23,
    "ScoreAchieved": 251,
    "NumAchievedHardcore": 23,
    "ScoreAchievedHardcore": 251
  },
  "2": {
    "NumPossibleAchievements": 22,
    "PossibleScore": 320,
    "NumAchieved": 22,
    "ScoreAchieved": 320,
    "NumAchievedHardcore": 22,
    "ScoreAchievedHardcore": 320
  },
  "3": {
    "NumPossibleAchievements": 23,
    "PossibleScore": 335,
    "NumAchieved": 23,
    "ScoreAchieved": 335,
    "NumAchievedHardcore": 23,
    "ScoreAchievedHardcore": 335
  }
}
json
{
  "1": {
    "numPossibleAchievements": 23,
    "possibleScore": 251,
    "numAchieved": 23,
    "scoreAchieved": 251,
    "numAchievedHardcore": 23,
    "scoreAchievedHardcore": 251
  },
  "2": {
    "numPossibleAchievements": 22,
    "possibleScore": 320,
    "numAchieved": 22,
    "scoreAchieved": 320,
    "numAchievedHardcore": 22,
    "scoreAchievedHardcore": 320
  },
  "3": {
    "numPossibleAchievements": 23,
    "possibleScore": 335,
    "numAchieved": 23,
    "scoreAchieved": 335,
    "numAchievedHardcore": 23,
    "scoreAchievedHardcore": 335
  }
}

Source

RepoURL
RAWebhttps://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserProgress.php
api-jshttps://github.com/RetroAchievements/api-js/blob/main/src/user/getUserProgress.ts
api-kotlinhttps://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt

Released under the MIT license.