From e36654f40163c3dc8f5f03aca528bbeb78b3a4b3 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 9 Apr 2026 22:18:21 +0000
Subject: [PATCH] docs: document request ID propagation for /v1/cubesql
 endpoint

Update REST API documentation to cover the request ID propagation feature
added in commit 1bce74bc1 (feat(api-gateway): propagate request ID for
REST /cubesql endpoint).

Changes:
- REST API overview (index.mdx): Update 'Request span annotation' section
  to explicitly list both /v1/load and /v1/cubesql as supporting request
  span annotation, document traceparent header support, and describe the
  auto-generated request ID format.
- REST API reference (reference.mdx): Add request span annotation note to
  the /v1/cubesql endpoint section explaining x-request-id and traceparent
  header support, and add a curl example with x-request-id header.

Co-authored-by: Pavel Tiunov <pavel.tiunov@gmail.com>
---
 .../core-data-apis/rest-api/index.mdx         | 20 ++++++++++++-------
 .../core-data-apis/rest-api/reference.mdx     | 18 +++++++++++++++++
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/docs/content/product/apis-integrations/core-data-apis/rest-api/index.mdx b/docs/content/product/apis-integrations/core-data-apis/rest-api/index.mdx
index 032af4e7111f7..b35e783288f52 100644
--- a/docs/content/product/apis-integrations/core-data-apis/rest-api/index.mdx
+++ b/docs/content/product/apis-integrations/core-data-apis/rest-api/index.mdx
@@ -264,13 +264,19 @@ Cube REST API has basic errors and HTTP Error codes for all requests.
 
 ### Request span annotation
 
-For monitoring tools such as Cube Cloud proper request span annotation should be
-provided in `x-request-id` header of a request. Each request id should consist
-of two parts: `spanId` and `requestSequenceId` which define `x-request-id` as
-whole: `${spanId}-span-${requestSequenceId}`. Values of `x-request-id` header
-should be unique for each separate request. `spanId` should define user
-interaction span such us `Continue wait` retry cycle and it's value shouldn't
-change during one single interaction.
+Both [`/v1/load`][ref-ref-load] and [`/v1/cubesql`][ref-ref-cubesql] endpoints
+support request span annotation for monitoring and tracing.
+
+You can provide a request ID via the `x-request-id` header or the `traceparent`
+header. Each request ID should consist of two parts: `spanId` and
+`requestSequenceId` which define `x-request-id` as whole:
+`${spanId}-span-${requestSequenceId}`. Values of `x-request-id` header should
+be unique for each separate request. `spanId` should define user interaction span
+such as `Continue wait` retry cycle and its value shouldn't change during one
+single interaction.
+
+If neither header is provided, Cube auto-generates a request ID in the
+`${uuid}-span-1` format.
 
 ## Cache control
 
diff --git a/docs/content/product/apis-integrations/core-data-apis/rest-api/reference.mdx b/docs/content/product/apis-integrations/core-data-apis/rest-api/reference.mdx
index 25ca3a0818c64..592e04f7a029c 100644
--- a/docs/content/product/apis-integrations/core-data-apis/rest-api/reference.mdx
+++ b/docs/content/product/apis-integrations/core-data-apis/rest-api/reference.mdx
@@ -335,6 +335,11 @@ This endpoint is part of the [SQL API][ref-sql-api].
 | `timezone` | The [time zone][ref-time-zone] for this query in the [TZ Database Name][link-tzdb] format, e.g., `America/Los_Angeles` | ❌ No |
 | `cache` | See [cache control][ref-cache-control]. `stale-if-slow` by default | ❌ No |
 
+This endpoint supports [request span annotation][ref-request-span]. You can
+pass the `x-request-id` or `traceparent` HTTP header to propagate your
+request ID through the entire SQL execution chain for tracing and monitoring.
+If neither header is provided, Cube auto-generates a request ID.
+
 Response: a stream of newline-delimited JSON objects. The first object contains
 the `schema` property with column names and types, and optionally
 `lastRefreshTime` indicating when the data was last refreshed.
@@ -381,6 +386,18 @@ Response:
 {"data":[["Max VERSTAPPEN","10","3.730769230769231"],["Lando NORRIS","4","4"],["Charles LECLERC","4","4.730769230769231"],["Oscar PIASTRI","3","4.8076923076923075"],["Andrea Kimi ANTONELLI","0","5"]]}
 ```
 
+Request with a custom request ID for tracing:
+
+```bash
+curl \
+  -X POST \
+  -H "Authorization: TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "x-request-id: my-trace-id-span-1" \
+  -d '{"query": "SELECT 123 AS value"}' \
+  http://localhost:4000/cubejs-api/v1/cubesql
+```
+
 ## `{base_path}/v1/pre-aggregations/jobs`
 
 Trigger pre-aggregation build jobs or retrieve statuses of such jobs.
@@ -883,3 +900,4 @@ Keep-Alive: timeout=5
 [link-tzdb]: https://en.wikipedia.org/wiki/Tz_database
 [ref-control-plane-api]: /product/apis-integrations/control-plane-api
 [self-metadata-api]: #metadata-api
+[ref-request-span]: /product/apis-integrations/rest-api#request-span-annotation