From 82576f7d54d644df0dcefce66e1f729e9f0a52ad Mon Sep 17 00:00:00 2001
From: smartinellibenedetti
 <139791797+smartinellibenedetti@users.noreply.github.com>
Date: Wed, 31 Dec 2025 17:56:32 -0700
Subject: [PATCH 1/5] update api docs

---
 docs/api/rundeck-api-versions.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/api/rundeck-api-versions.md b/docs/api/rundeck-api-versions.md
index b8abcfc9e..dc81c5da9 100644
--- a/docs/api/rundeck-api-versions.md
+++ b/docs/api/rundeck-api-versions.md
@@ -35,6 +35,12 @@ 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 (fast, returns empty metrics (all zeros) if no stats exist). 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.
+  * [`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 (fast, returns empty metrics (all zeros) if no stats exist). 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).
+
 ### Version 56
 
 * Updated Endpoints:

From ab231334dddc952058f32f4bb69eeff5a2ce5d73 Mon Sep 17 00:00:00 2001
From: smartinellibenedetti
 <139791797+smartinellibenedetti@users.noreply.github.com>
Date: Wed, 31 Dec 2025 18:03:29 -0700
Subject: [PATCH 2/5] Update index.md

---
 docs/api/index.md | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/docs/api/index.md b/docs/api/index.md
index 4439e01e4..a142736f2 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -3911,10 +3911,14 @@ 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 (fast, returns empty metrics (all zeros) if no stats exist). If `false` or not provided, use execution table query. When `useStats=true`, the `jobIdListFilter` parameter is required for the system-wide endpoint.
+* `groupByJob` (boolean): If `true` with `useStats=true`, returns metrics for all jobs in the project (batch mode). Requires `project` parameter. Returns format: `{jobs: {uuid1: metrics, uuid2: metrics, ...}}`. This parameter can only be used with the project-specific endpoint.
 
+**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 +3931,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
 

From 678de44ee279dfa15408e41eba9a93959714c615 Mon Sep 17 00:00:00 2001
From: smartinellibenedetti
 <139791797+smartinellibenedetti@users.noreply.github.com>
Date: Fri, 2 Jan 2026 16:27:09 -0700
Subject: [PATCH 3/5] doc fixes

---
 docs/api/index.md                | 6 ++++--
 docs/api/rundeck-api-versions.md | 4 ++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/api/index.md b/docs/api/index.md
index a142736f2..1721cd17d 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -3913,8 +3913,10 @@ Paging parameters `max` and `offset` will have no effect on the result.
 
 **Additional Parameters (API v57+):**
 
-* `useStats` (boolean): If `true`, use snapshot-based metrics from SCHEDULED_EXECUTION_STATS table (fast, returns empty metrics (all zeros) if no stats exist). If `false` or not provided, use execution table query. When `useStats=true`, the `jobIdListFilter` parameter is required for the system-wide endpoint.
-* `groupByJob` (boolean): If `true` with `useStats=true`, returns metrics for all jobs in the project (batch mode). Requires `project` parameter. Returns format: `{jobs: {uuid1: metrics, uuid2: metrics, ...}}`. This parameter can only be used with the project-specific endpoint.
+* `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 the project (batch mode). Requires `project` parameter. 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-dd'T'HH:mm:ss'Z'` (ISO8601).
+* `end` (string): When using `useStats=true`, filter metrics to include only executions that completed on or before this date. Format: `yyyy-MM-dd'T'HH:mm:ss'Z'` (ISO8601).
 
 **Response**
 
diff --git a/docs/api/rundeck-api-versions.md b/docs/api/rundeck-api-versions.md
index dc81c5da9..613c63847 100644
--- a/docs/api/rundeck-api-versions.md
+++ b/docs/api/rundeck-api-versions.md
@@ -38,8 +38,8 @@ API versions below `{{$apiDepVersion}}` are *deprecated*.  Clients using earlier
 ### 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 (fast, returns empty metrics (all zeros) if no stats exist). 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.
-  * [`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 (fast, returns empty metrics (all zeros) if no stats exist). 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).
+  * [`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
 

From 59cf477e9f239d63b10a623e80f5a9ff80edb9e4 Mon Sep 17 00:00:00 2001
From: smartinellibenedetti
 <139791797+smartinellibenedetti@users.noreply.github.com>
Date: Fri, 2 Jan 2026 16:44:24 -0700
Subject: [PATCH 4/5] Update docs/api/index.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/api/index.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/api/index.md b/docs/api/index.md
index 1721cd17d..769480622 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -3915,8 +3915,8 @@ Paging parameters `max` and `offset` will have no effect on the result.
 
 * `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 the project (batch mode). Requires `project` parameter. 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-dd'T'HH:mm:ss'Z'` (ISO8601).
-* `end` (string): When using `useStats=true`, filter metrics to include only executions that completed on or before this date. Format: `yyyy-MM-dd'T'HH:mm:ss'Z'` (ISO8601).
+* `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**
 

From da3f2b2322215f1194caaf3f95f18ef92f7bcf3c Mon Sep 17 00:00:00 2001
From: smartinellibenedetti
 <139791797+smartinellibenedetti@users.noreply.github.com>
Date: Fri, 2 Jan 2026 16:44:44 -0700
Subject: [PATCH 5/5] Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 docs/api/index.md                |  2 +-
 docs/api/rundeck-api-versions.md | 10 ++++++++--
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/docs/api/index.md b/docs/api/index.md
index 769480622..89ad1fa41 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -3914,7 +3914,7 @@ Paging parameters `max` and `offset` will have no effect on the result.
 **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 the project (batch mode). Requires `project` parameter. Returns format: `{jobs: {uuid1: metrics, uuid2: metrics, ...}}`.
+* `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).
 
diff --git a/docs/api/rundeck-api-versions.md b/docs/api/rundeck-api-versions.md
index 613c63847..cb1f63d6d 100644
--- a/docs/api/rundeck-api-versions.md
+++ b/docs/api/rundeck-api-versions.md
@@ -38,8 +38,14 @@ API versions below `{{$apiDepVersion}}` are *deprecated*.  Clients using earlier
 ### 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`.
+  * [`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