RUN-3768: Update API docs with changes for job metrics plugin

docs/api/index.md

@@ -3911,10 +3911,16 @@ To narrow down the result set over which the metrics will be calculated, you can
 
 Paging parameters `max` and `offset` will have no effect on the result.
 
-**Response**
+**Additional Parameters (API v57+):**
+
+* `useStats` (boolean): If `true`, use snapshot-based metrics from SCHEDULED_EXECUTION_STATS table. If `false` or not provided, use execution table query. When `useStats=true`, the `jobIdListFilter` parameter is required unless `groupByJob=true`.
+* `groupByJob` (boolean): If `true` with `useStats=true`, returns metrics for all jobs in a single project (batch mode). The metrics query must be scoped to one project, either by using the project-specific endpoint (`/api/29/project/[PROJECT]/executions/metrics`) or by including a `project` query parameter when calling the global endpoint (`/api/29/executions/metrics`). Returns format: `{jobs: {uuid1: metrics, uuid2: metrics, ...}}`.
+* `begin` (string): When using `useStats=true`, filter metrics to include only executions that completed on or after this date. Format: `yyyy-MM-ddTHH:mm:ssZ` (ISO8601).
+* `end` (string): When using `useStats=true`, filter metrics to include only executions that completed on or before this date. Format: `yyyy-MM-ddTHH:mm:ssZ` (ISO8601).
 
+**Response**
 
-An object with `duration` entry containing duration stats, and a `total` entry with total executions.
+When `groupByJob` is not used, the response is an object with `duration` entry containing duration stats, and a `total` entry with total executions:
 
 ``` json
 {
@@ -3927,6 +3933,33 @@ An object with `duration` entry containing duration stats, and a `total` entry w
 }
 ```
 
+When `groupByJob=true` with `useStats=true` (API v57+), the response format is:
+
+``` json
+{
+    "jobs": {
+        "uuid1": {
+            "total": 100,
+            "succeeded": 95,
+            "failed": 5,
+            "duration": {
+                "average": "5s"
+            },
+            ...
+        },
+        "uuid2": {
+            "total": 50,
+            "succeeded": 48,
+            "failed": 2,
+            "duration": {
+                "average": "3s"
+            },
+            ...
+        }
+    }
+}
+```
+
 
 ### Execution State
 

docs/api/rundeck-api-versions.md

@@ -35,6 +35,18 @@ Changes introduced by API Version number:
 API versions below `{{$apiDepVersion}}` are *deprecated*.  Clients using earlier versions should upgrade to use `{{$apiDepVersion}}` as the minimum version before release `{{ $apiDepRelease }}` to avoid errors.
 :::
 
+### Version 57
+
+* Updated Endpoints:
+  * [`GET /api/V/executions/metrics`][/api/V/executions/metrics]
+    * Added `useStats` parameter: if `true`, use snapshot-based metrics from `SCHEDULED_EXECUTION_STATS` table. If `false` or not provided, use execution table query.
+    * Added `groupByJob` parameter: if `true` with `useStats=true`, returns metrics for all jobs in the project (batch mode). Requires `project` parameter.
+    * Added `begin` and `end` parameters for date range filtering when using `useStats=true`.
+  * [`GET /api/V/project/[PROJECT]/executions/metrics`][/api/V/project/\[PROJECT\]/executions/metrics]
+    * Added `useStats` parameter: if `true`, use snapshot-based metrics from `SCHEDULED_EXECUTION_STATS` table. If `false` or not provided, use execution table query.
+    * Added `groupByJob` parameter: if `true` with `useStats=true`, returns metrics for all jobs in the project (batch mode).
+    * Added `begin` and `end` parameters for date range filtering when using `useStats=true`.
+
 ### Version 56
 
 * Updated Endpoints: