From 096ecc9e1e57071935e65038b2d9c50686b586a5 Mon Sep 17 00:00:00 2001
From: "sentry-junior[bot]"
 <264270552+sentry-junior[bot]@users.noreply.github.com>
Date: Sat, 7 Nov 2026 01:17:28 +0000
Subject: [PATCH] docs(explore): Document repeated yAxis, interval units, and
 trace timestamp

The events timeseries endpoint reads yAxis with getlist and returns one
timeseries per aggregate, but the docs typed it as a single string. Its
interval, shared with the dropped events endpoint, goes through
parse_stats_period, which accepts a unit suffix such as 5m or 1h, but the
docs typed it as an integer.

The trace and trace meta endpoints narrow their query window around an
optional timestamp parameter that the docs didn't list.

Document yAxis as repeatable, interval as an integer or a string with a
unit suffix, and the timestamp parameter on both trace endpoints.

Refs getsentry/toolkit#2073

Co-Authored-By: BYK <126780+BYK@users.noreply.github.com>
---
 .../api/endpoints/organization_trace.py       |  1 +
 .../api/endpoints/organization_trace_meta.py  |  1 +
 src/sentry/apidocs/parameters.py              | 25 ++++++++++++++++---
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/sentry/api/endpoints/organization_trace.py b/src/sentry/api/endpoints/organization_trace.py
index f75da40f9b11..f6a7b1fe403b 100644
--- a/src/sentry/api/endpoints/organization_trace.py
+++ b/src/sentry/api/endpoints/organization_trace.py
@@ -120,6 +120,7 @@ def query_trace_data(
             GlobalParams.START,
             GlobalParams.END,
             REFERRER_QUERY_PARAM,
+            TraceParams.TIMESTAMP,
             ERROR_ID_QUERY_PARAM,
             ADDITIONAL_ATTRIBUTES_PARAM,
             INCLUDE_UPTIME_PARAM,
diff --git a/src/sentry/api/endpoints/organization_trace_meta.py b/src/sentry/api/endpoints/organization_trace_meta.py
index 4ef998014f32..a9996b942ce8 100644
--- a/src/sentry/api/endpoints/organization_trace_meta.py
+++ b/src/sentry/api/endpoints/organization_trace_meta.py
@@ -276,6 +276,7 @@ def query_meta_data(
             GlobalParams.STATS_PERIOD,
             GlobalParams.START,
             GlobalParams.END,
+            TraceParams.TIMESTAMP,
             INCLUDE_UPTIME_PARAM,
         ],
         responses={
diff --git a/src/sentry/apidocs/parameters.py b/src/sentry/apidocs/parameters.py
index 2d004877231f..ee8360e737c9 100644
--- a/src/sentry/apidocs/parameters.py
+++ b/src/sentry/apidocs/parameters.py
@@ -915,9 +915,15 @@ class VisibilityParams:
         name="interval",
         location="query",
         required=False,
-        type=int,
+        type={
+            "anyOf": [
+                {"type": "integer"},
+                {"type": "string", "pattern": r"^\d+[smhdw]?$"},
+            ]
+        },
         description="""The size of the bucket for the timeseries to have, must be a value smaller than the window being
-queried. If the interval is invalid a default interval will be selected instead""",
+queried. Either a number of seconds, or a number with a unit suffix of `s`, `m`, `h`, `d`, or `w`, such as `5m` or
+`1h`. If the interval is invalid a default interval will be selected instead""",
     )
     GROUP_BY = OpenApiParameter(
         name="groupBy",
@@ -933,8 +939,10 @@ class VisibilityParams:
         location="query",
         required=False,
         type=str,
-        description="""The aggregate field to create the timeseries for, defaults to `count()` when
-        not included.
+        many=True,
+        description="""The aggregate fields to create timeseries for, defaults to `count()` when
+        not included. Pass the parameter more than once to get a timeseries for each aggregate, for
+        example `?yAxis=count()&yAxis=p95(span.duration)`.
 - `count()` - Total count of events over the period.
 - `avg(field)` - Average value of the field over the period.
 - `pXX(field)` - Percentile value of the field over the period. One of: `p50`, `p75`, `p90`, `p95`, `p99`, `p100`.
@@ -1133,6 +1141,15 @@ class TraceParams:
         type=str,
         description="The ID of the trace, a 32-character hexadecimal string.",
     )
+    TIMESTAMP = OpenApiParameter(
+        name="timestamp",
+        location="query",
+        required=False,
+        type=str,
+        description="""The timestamp of an event in the trace, as an ISO 8601 string or Unix timestamp in
+seconds. When passed, the query is narrowed to a window around this time, which is faster than
+searching the full time range.""",
+    )
 
 
 class ProjectParams: