Skip to content

User Completion Progress

A call to this endpoint will retrieve a giver user's completion progress, targeted by their username.

On-site Representation

A user's completion progress can be found in several places, most prolifically on their Completion Progress page:

Completion Progress

HTTP Request

GET

https://retroachievements.org/API/API_GetUserCompletionProgress.php?u=MaxMilyin

Query Parameters

NameRequired?Description
zYesYour username.
yYesYour web API key.
uYesThe target username.
cCount, number of records to return (default: 100, max: 500).
oOffset, number of entries to skip (default: 0).

Client Library

ts
import {
  buildAuthorization,
  getUserCompletionProgress,
} 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 userCompletionProgress = await getUserCompletionProgress(authorization, {
  username: "MaxMilyin",
});
kotlin
val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserCompletionProgress.Response, ErrorResponse> = api.getUserCompletionProgress(
    username = "MaxMilyin",
)

if (response is NetworkResponse.Success) {
    // handle the data
    val completionProgress: GetUserCompletionProgress.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
{
  "Count": 100,
  "Total": 1287,
  "Results": [
    {
      "GameID": 20246,
      "Title": "~Hack~ Knuckles the Echidna in Sonic the Hedgehog",
      "ImageIcon": "/Images/074560.png",
      "ConsoleID": 1,
      "ConsoleName": "Mega Drive / Genesis",
      "MaxPossible": 0,
      "NumAwarded": 0,
      "NumAwardedHardcore": 0,
      "MostRecentAwardedDate": "2023-10-27T02:52:34+00:00",
      "HighestAwardKind": "beaten-hardcore",
      "HighestAwardDate": "2023-10-27T02:52:34+00:00"
    }
    // ...
  ]
}
json
{
  "count": 100,
  "total": 1287,
  "results": [
    {
      "gameId": 20246,
      "title": "~Hack~ Knuckles the Echidna in Sonic the Hedgehog",
      "imageIcon": "/Images/074560.png",
      "consoleId": 1,
      "consoleName": "Mega Drive / Genesis",
      "maxPossible": 0,
      "numAwarded": 0,
      "numAwardedHardcore": 0,
      "mostRecentAwardedDate": "2023-10-27T02:52:34+00:00",
      "highestAwardKind": "beaten-hardcore",
      "highestAwardDate": "2023-10-27T02:52:34+00:00"
    }
    // ...
  ]
}

Source

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

Released under the MIT license.