From a58f9fa86dceb56210ed1ad7ac1b5ce97135b66a Mon Sep 17 00:00:00 2001
From: Adam E <159158755+adam-saucelabs@users.noreply.github.com>
Date: Mon, 25 Nov 2024 08:39:49 -0600
Subject: [PATCH 1/3] Update insights endpoints to clarify optional/required
 params

adding note to two endpoints that did not have information about XOR on start/end or time_range
---
 docs/dev/api/insights.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/dev/api/insights.md b/docs/dev/api/insights.md
index 67d624d925..0062f1c456 100644
--- a/docs/dev/api/insights.md
+++ b/docs/dev/api/insights.md
@@ -24,6 +24,10 @@ Return run data for all tests that match the request criteria.
 
 #### Parameters
 
+:::note
+This call requires <code>start</code> and <code>end</code> parameters OR the <code>time_range</code> parameter.
+:::
+
 <table id="table-api">
   <tbody>
     <tr>
@@ -412,6 +416,10 @@ Return a set of data "buckets" representing tests that were run in each time int
 
 #### Parameters
 
+:::note
+This call requires <code>start</code> and <code>end</code> parameters OR the <code>time_range</code> parameter.
+:::
+
 <table id="table-api">
   <tbody>
     <tr>

From de3a004e46386af7fb7358ae8269d962ee75299b Mon Sep 17 00:00:00 2001
From: Adam E <159158755+adam-saucelabs@users.noreply.github.com>
Date: Mon, 25 Nov 2024 10:08:13 -0600
Subject: [PATCH 2/3] start/end/time_range consistency updates

updating copy for start/end/time_range and parameter sorting for

- /v1/analytics/tests
- /v1/analytics/insights/test-metrics
- /v1/analytics/trends/tests
- /v1/analytics/trends/builds_tests
---
 docs/dev/api/insights.md | 75 +++++++++++++++++++---------------------
 1 file changed, 36 insertions(+), 39 deletions(-)

diff --git a/docs/dev/api/insights.md b/docs/dev/api/insights.md
index 0062f1c456..9727a49997 100644
--- a/docs/dev/api/insights.md
+++ b/docs/dev/api/insights.md
@@ -29,6 +29,24 @@ This call requires <code>start</code> and <code>end</code> parameters OR the <co
 :::
 
 <table id="table-api">
+    <tbody>
+    <tr>
+     <td><code>start</code></td>
+       <td><p><small>| QUERY | REQUIRED | DATE |</small></p><p>The starting date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
+    </tr>
+  </tbody>
+  <tbody>
+    <tr>
+     <td><code>end</code></td>
+       <td><p><small>| QUERY | REQUIRED | DATE |</small></p><p>The ending date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
+    </tr>
+  </tbody>
+  <tbody>
+    <tr>
+     <td><code>time_range</code></td>
+       <td><p><small>| QUERY | REQUIRED | DURATION + UNIT |</small></p><p>The amount of time backward from the current time that represents the period during which the test runs are executed. Acceptable units include <code>d</code> (day); <code>h</code> (hour); <code>m</code> (minute); <code>s</code> (second).</p></td>
+    </tr>
+  </tbody>
   <tbody>
     <tr>
      <td><code>build</code></td>
@@ -47,12 +65,6 @@ This call requires <code>start</code> and <code>end</code> parameters OR the <co
      <td><p><small>| QUERY | OPTIONAL | BOOLEAN |</small></p><p>Sort results by test creation time. Default value is <code>true</code>.</p></td>
     </tr>
   </tbody>
-  <tbody>
-    <tr>
-     <td><code>end</code></td>
-       <td><p><small>| QUERY | OPTIONAL | DATE |</small></p><p>The ending date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
-    </tr>
-  </tbody>
   <tbody>
     <tr>
      <td><code>error</code></td>
@@ -99,12 +111,6 @@ This call requires <code>start</code> and <code>end</code> parameters OR the <co
      <td><p><small>| QUERY | OPTIONAL | INTEGER |</small></p><p>The maximum number of results to return. Default value is <code>10</code></p></td>
     </tr>
   </tbody>
-  <tbody>
-    <tr>
-     <td><code>start</code></td>
-       <td><p><small>| QUERY | OPTIONAL | DATE |</small></p><p>The starting date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
-    </tr>
-  </tbody>
   <tbody>
     <tr>
      <td><code>status</code></td>
@@ -122,15 +128,6 @@ This call requires <code>start</code> and <code>end</code> parameters OR the <co
         </td>
     </tr>
   </tbody>
-  <tbody>
-    <tr>
-     <td><code>time_range</code></td>
-        <td>
-            <p><small>| QUERY | OPTIONAL | STRING |</small></p>
-            <p>The amount of time backward from the current time that represents the period during which the test runs are executed. Acceptable units include <code>d</code> (day); <code>h</code> (hour); <code>m</code> (minute); <code>s</code> (second).</p>
-        </td>
-    </tr>
-  </tbody>
 </table>
 
 <Tabs
@@ -421,6 +418,24 @@ This call requires <code>start</code> and <code>end</code> parameters OR the <co
 :::
 
 <table id="table-api">
+    <tbody>
+    <tr>
+     <td><code>start</code></td>
+       <td><p><small>| QUERY | REQUIRED | DATE |</small></p><p>The starting date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
+    </tr>
+  </tbody>
+  <tbody>
+    <tr>
+     <td><code>end</code></td>
+       <td><p><small>| QUERY | REQUIRED | DATE |</small></p><p>The ending date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
+    </tr>
+  </tbody>
+  <tbody>
+    <tr>
+     <td><code>time_range</code></td>
+       <td><p><small>| QUERY | REQUIRED | DURATION + UNIT |</small></p><p>The amount of time backward from the current time that represents the period during which the test runs are executed. Acceptable units include <code>d</code> (day); <code>h</code> (hour); <code>m</code> (minute); <code>s</code> (second).</p></td>
+    </tr>
+  </tbody>
   <tbody>
     <tr>
      <td><code>scope</code></td>
@@ -446,24 +461,6 @@ This call requires <code>start</code> and <code>end</code> parameters OR the <co
      </td>
     </tr>
   </tbody>
-  <tbody>
-    <tr>
-     <td><code>time_range</code></td>
-       <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>The amount of time backward from the current time that represents the period during which the test runs are executed. Acceptable units include <code>d</code> (day); <code>h</code> (hour); <code>m</code> (minute); <code>s</code> (second).</p></td>
-    </tr>
-  </tbody>
-  <tbody>
-    <tr>
-     <td><code>start</code></td>
-       <td><p><small>| QUERY | OPTIONAL | DATE |</small></p><p>The starting date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
-    </tr>
-  </tbody>
-  <tbody>
-    <tr>
-     <td><code>end</code></td>
-       <td><p><small>| QUERY | OPTIONAL | DATE |</small></p><p>The ending date of the period during which the test runs executed, in <code>YYYY-MM-DDTHH:mm:ssZ</code> (UTC) format.</p></td>
-    </tr>
-  </tbody>
   <tbody>
     <tr>
      <td><code>browser</code></td>

From 8df24ba118cc43b51478c39f57e918519fe7352b Mon Sep 17 00:00:00 2001
From: Adam E <159158755+adam-saucelabs@users.noreply.github.com>
Date: Mon, 25 Nov 2024 10:15:54 -0600
Subject: [PATCH 3/3] update interval parameter for all endpoints

---
 docs/dev/api/insights.md | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/dev/api/insights.md b/docs/dev/api/insights.md
index 9727a49997..0495d94207 100644
--- a/docs/dev/api/insights.md
+++ b/docs/dev/api/insights.md
@@ -457,7 +457,7 @@ This call requires <code>start</code> and <code>end</code> parameters OR the <co
      <td><code>interval</code></td>
      <td>
          <p><small>| QUERY | OPTIONAL | STRING |</small></p>
-         <p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p>
+         <p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p>
      </td>
     </tr>
   </tbody>
@@ -1803,8 +1803,8 @@ Return an array of errors with occurrence count on all tests run in the specifie
             <p><small>| QUERY | OPTIONAL | STRING |</small></p>
             <p>
                 Relative date filter. Available values are: <ul>
-                <li><code>1m</code> (1 month)</li>
-                <li><code>15m</code> (15 months)</li>
+                <li><code>1m</code> (1 minute)</li>
+                <li><code>15m</code> (15 minutes)</li>
                 <li><code>1h</code> (1 hour)</li>
                 <li><code>6h</code> (6 hours)</li>
                 <li><code>12h</code> (12 hours)</li>
@@ -1970,7 +1970,7 @@ Return past and current data about errors for comparison.
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -2595,7 +2595,7 @@ Return an array of test cases (grouped by name) with statistical details.
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -2811,7 +2811,7 @@ Return an array of test cases (grouped by name) with statistical details as a CS
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -3007,7 +3007,7 @@ Return an array of test cases (grouped by name) with statistical details.
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -3521,7 +3521,7 @@ Return information about tests coverage for the specified <code>coverage_field</
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -3805,7 +3805,7 @@ Return information about tests coverage for the specified `coverage_field` in a
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -4041,7 +4041,7 @@ Return an array of buckets with aggregations, such as number of tests run on a s
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -4327,7 +4327,7 @@ Return an array of buckets with aggregations, such as the number of tests from a
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -4625,7 +4625,7 @@ Return statistics for errors that occurred in tests run in the specified period.
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>
@@ -5009,7 +5009,7 @@ Return information about builds and tests run included in the build. Also, it pr
   <tbody>
     <tr>
      <td><code>interval</code></td>
-     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 month)</li><li><code>15m</code> (15 months)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
+     <td><p><small>| QUERY | OPTIONAL | STRING |</small></p><p>Relative date filter. Available values are: <ul><li><code>1m</code> (1 minute)</li><li><code>15m</code> (15 minutes)</li><li><code>1h</code> (1 hour)</li><li><code>6h</code> (6 hours)</li><li><code>12h</code> (12 hours)</li><li><code>1d</code> (1 day)</li><li><code>7d</code> (7 days)</li><li><code>30d</code> (30 days)</li></ul>Default value is <code>1d</code></p></td>
     </tr>
   </tbody>
   <tbody>