From 7e3c4c472ccb28c83a6c36fd8d474ca10f49b7b0 Mon Sep 17 00:00:00 2001
From: Wes Copeland <wlcopeland1@gmail.com>
Date: Mon, 28 Jul 2025 21:24:22 -0400
Subject: [PATCH] docs: add page for API_GetGameProgression

---
 README.md                       |  1 +
 docs/.vitepress/config.mts      |  4 ++
 docs/v1/get-game-progression.md | 86 +++++++++++++++++++++++++++++++++
 3 files changed, 91 insertions(+)
 create mode 100644 docs/v1/get-game-progression.md

diff --git a/README.md b/README.md
index d8fe766..5646631 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,7 @@ Click the function names to open their complete docs on the docs site.
 - [Achievement IDs](https://api-docs.retroachievements.org/v1/get-achievement-count.html) - Get the list of achievement IDs for a game.
 - [Unlocks Distribution](https://api-docs.retroachievements.org/v1/get-achievement-distribution.html) - Get how many players have unlocked how many achievements for a game.
 - [High Scores](https://api-docs.retroachievements.org/v1/get-game-rank-and-score.html) - Get a list of either the latest masters or highest hardcore points earners for a game.
+- [Progression](https://api-docs.retroachievements.org/v1/get-game-progression.html) - Get information about average time to unlock achievements for a game.
 
 ### Leaderboards
 
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 7346080..cbb23bb 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -152,6 +152,10 @@ export default defineConfig({
             text: "High Scores",
             link: "/v1/get-game-rank-and-score",
           },
+          {
+            text: "Progression",
+            link: "/v1/get-game-progression",
+          },
         ],
       },
       {
diff --git a/docs/v1/get-game-progression.md b/docs/v1/get-game-progression.md
new file mode 100644
index 0000000..b426f9e
--- /dev/null
+++ b/docs/v1/get-game-progression.md
@@ -0,0 +1,86 @@
+<script setup>
+import SampleRequest from '../components/SampleRequest.vue';
+</script>
+
+# Game Progression
+
+A call to this endpoint will retrieve information about the average time to unlock achievements in a game, targeted via its unique ID.
+
+[[toc]]
+
+## HTTP Request
+
+<SampleRequest httpVerb="GET">https://retroachievements.org/API/API_GetGameProgression.php?i=228</SampleRequest>
+
+### Query Parameters
+
+| Name | Required? | Description                                                               |
+| :--- | :-------- | :------------------------------------------------------------------------ |
+| `y`  | Yes       | Your web API key.                                                         |
+| `i`  | Yes       | The target game ID.                                                       |
+| `h`  |           | 1 to prefer players with more hardcore unlocks than non-hardcore unlocks. |
+
+## Response
+
+::: code-group
+
+```json [HTTP Response]
+{
+  "ID": 228,
+  "Title": "Super Mario World",
+  "ConsoleID": 3,
+  "ConsoleName": "SNES/Super Famicom",
+  "ImageIcon": "/Images/112443.png",
+  "NumDistinctPlayers": 79281,
+  "TimesUsedInBeatMedian": 4493,
+  "TimesUsedInHardcoreBeatMedian": 8249,
+  "MedianTimeToBeat": 17878,
+  "MedianTimeToBeatHardcore": 19224,
+  "TimesUsedInCompletionMedian": 155,
+  "TimesUsedInMasteryMedian": 1091,
+  "MedianTimeToComplete": 67017,
+  "MedianTimeToMaster": 79744,
+  "NumAchievements": 89,
+  "Achievements": [
+    {
+      "ID": 342,
+      "Title": "Giddy Up!",
+      "Description": "Catch a ride with a friend",
+      "Points": 1,
+      "TrueRatio": 1,
+      "Type": null,
+      "BadgeName": "46580",
+      "NumAwarded": 75168,
+      "NumAwardedHardcore": 37024,
+      "TimesUsedInUnlockMedian": 63,
+      "TimesUsedInHardcoreUnlockMedian": 69,
+      "MedianTimeToUnlock": 274,
+      "MedianTimeToUnlockHardcore": 323
+    },
+    {
+      "ID": 341,
+      "Title": "Unleash The Dragon",
+      "Description": "Collect 5 Dragon Coins in a level",
+      "Points": 2,
+      "TrueRatio": 2,
+      "Type": null,
+      "BadgeName": "46591",
+      "NumAwarded": 66647,
+      "NumAwardedHardcore": 34051,
+      "TimesUsedInUnlockMedian": 66,
+      "TimesUsedInHardcoreUnlockMedian": 70,
+      "MedianTimeToUnlock": 290,
+      "MedianTimeToUnlockHardcore": 333
+    }
+    // ... additional achievements
+  ]
+}
+```
+
+:::
+
+## Source
+
+| Repo  | URL                                                                                          |
+| :---- | :------------------------------------------------------------------------------------------- |
+| RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetGameProgression.php |