Reading metrics via the Remote API

1. In the management console, go to the folder that stores your data.
2. Create a service account with the monitoring.viewer role for the selected folder.
3. Create an API key for the service account.
4. Add the endpoint (url) to the remote_read section of the Prometheus configuration:

   ...
   remote_read:
     ...
     - url: '<URL>' # You can get it upon request.
       bearer_token: '<API_key>'
       # Alternatively, you can use a file (recommended):
       # bearer_token_file: '<name_of_file_with_API_key>'
   
       # We recommend adding the `X-Lookback-Delta` custom header.
       # If you did not change the `lookback-delta` value in
       # your Prometheus instance configuration, specify the default value, `5m`.
       # This information is required for optimized decimation.
       headers:
         X-Lookback-Delta: 5m
   
       # The default behavior limits data queries to time ranges
       # missing from the Prometheus local storage (usually those beyond the storage retention).
       # If your reads and writes use different Prometheus instances,
       # consider enabling the following option to always fetch data:
       # [ read_recent: true ]
   
       # If you only want to read specific metrics via the Remote API, provide their labels:
       # required_matchers:
       # [ <label_name>: <label_value> ... ]
   

5. Restart Prometheus or reload the configuration.

Error examplesError examples

Prometheus metricsPrometheus metrics

Current limitationsCurrent limitations

• The maximum number of time series you can get metadata for using the /api/v1/series query is 10,000.
• The maximum number of time series you can read per one /api/v1/query or /api/v1/query_range query is 10,000.

© 2025 Linux Foundation. All rights reserved. The Linux Foundation owns and uses registered trademarks. For a list of Linux Foundation trademarks, see Trademark Usage.