From dde7d6ad3797f4c304f957400732f0a5f29e177c Mon Sep 17 00:00:00 2001 From: Simon Pasquier Date: Tue, 23 Sep 2025 13:03:14 +0200 Subject: [PATCH] doc: clarify start/end for label API endpoints (#17217) Because the label API endpoints read from the TSDB indexes, they can return information for series which are present in the index but have no samples in the queried interval. Add similar note for the series endpoint. Signed-off-by: Simon Pasquier --- docs/querying/api.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/querying/api.md b/docs/querying/api.md index 2f3c79cef7..67df15d0a7 100644 --- a/docs/querying/api.md +++ b/docs/querying/api.md @@ -348,7 +348,9 @@ You can URL-encode these parameters directly in the request body by using the `P or dynamic number of series selectors that may breach server-side URL character limits. The `data` section of the query result consists of a list of objects that -contain the label name/value pairs which identify each series. +contain the label name/value pairs which identify each series. Note that the +`start` and `end` times are approximate and the result may contain label values +for series which have no samples in the given interval. The following example returns all series that match either of the selectors `up` or `process_start_time_seconds{job="prometheus"}`: @@ -397,8 +399,9 @@ URL query parameters: series from which to read the label names. Optional. - `limit=`: Maximum number of returned series. Optional. 0 means disabled. - -The `data` section of the JSON response is a list of string label names. +The `data` section of the JSON response is a list of string label names. Note +that the `start` and `end` times are approximate and the result may contain +label names for series which have no samples in the given interval. Here is an example. @@ -451,7 +454,10 @@ URL query parameters: series from which to read the label values. Optional. - `limit=`: Maximum number of returned series. Optional. 0 means disabled. -The `data` section of the JSON response is a list of string label values. +The `data` section of the JSON response is a list of string label values. Note +that the `start` and `end` times are approximate and the result may contain +label values for series which have no samples in the given interval. + This example queries for all label values for the `http_status_code` label: