Azure Monitor Metrics Batch API – top Parameter Behavior and Complete Time Series Retrieval

Hi @Ninave, Durgesh (Contractor) Thank you for reaching out to Microsoft Q&A. We are looking into the issue and we will get back to you shortly with an update

Hello Ninave Durgesh,

Thank you for reaching out to Microsoft Q&A.

Based on the provided documentation, here’s what we can clarify for production usage of the Azure Monitor Metrics Batch API (metrics:getBatch, api-version 2023-10-01) around the top parameter and complete retrieval.

For metrics:getBatch, API version 2023-10-01, the important distinction is between the parameter’s documented numeric type and a guarantee that every matching time series will be returned.

Behavior of top and detecting omitted series

The top parameter defaults to 10 when a filter applies and limits the returned time series per metric, per resource ID not the entire batch or the datapoints within a series.

Additional matching series can be excluded by this limit. The published REST reference does not document an omitted-series count, total matching-series count, continuation token, or TopN-specific truncation flag/header. Therefore, a successful response alone should not be interpreted as confirmation of complete retrieval.

As a client-side safeguard, count the timeseries entries for each resource/metric pair. A count equal to top indicates possible limiting, but does not prove omission: exactly that many series might match. A count below top also does not independently establish end-to-end completeness.

Maximum value of top

The parameter is documented as integer (int32), whose maximum representable value is 2,147,483,647. Your observation that 2,147,483,648 returns BadRequest with Detected invalid TopN value ... should be Int value is consistent with that boundary.

However, the documentation reviewed does not separately guarantee that setting top=2147483647 retrieves every matching series or supports responses containing that many series. We therefore cannot confirm it as an “unlimited” production setting.

Recommended retrieval approach

Microsoft recommends splitting large queries into multiple parallel queries, because paging is unsupported. Each batch supports up to 50 unique resource IDs, belonging to the same subscription, region, and resource type.

Based on these documented behaviors, our suggested implementation approach is:

1. Create compatible resource batches. Verify the resource count and subscription, region, and resource-type grouping.
2. Partition high-cardinality dimension values into exhaustive, non-overlapping filters. Set an explicit top above each partition’s bounded series count per resource/metric. Preserve the dimensions you need separately rather than merging them through rollupby. Verify: Compare returned dimension combinations with the expected inventory for the requested time window, including historical values.
3. Split by metric or shorter time windows additionally to control response size. Splitting only by resource, metric, or time does not guarantee avoidance of the per-resource/per-metric cap. Verify: Ensure all intended resource, metric, dimension, and time-window partitions are covered.
4. Validate each partition before marking collection complete. Inspect individual metric errorCode/errorMessage fields. Use controlled concurrency and exponential backoff for HTTP 529 responses. Verify: Confirm successful retrieval and storage of every partition, including retries.

These safeguards are an engineering recommendation, not a published unconditional completeness guarantee. If the dimension inventory cannot be exhaustively established, we recommend requesting Azure Monitor support clarification before relying on this approach for a strict no-missing-series requirement.

Questions to validate your scenario

1. Have you observed missing time series, or is this a clarification before production rollout? If omissions occurred, what were the expected and returned series counts for one resource/metric pair, and how was the expected set established?
2. Could you share one sanitized request and its complete response? Include namespace, metric names, filter, top, orderby, rollupby, start/end times, interval, response headers, and the complete error body from the boundary test.
3. If you have already compared a larger top or narrower filters, did additional dimension combinations appear? Were the historical time window and remaining parameters unchanged? No additional large-volume testing is needed at this stage.
4. Are dimension values fixed or dynamically created? Please also confirm the resource type, region, client/SDK version, reproduction scope, and whether the query or client changed before the observed behavior.
5. For a failed or incomplete example, what was the exact UTC timestamp and any available Request, Correlation, or Trace ID? Were there timeouts, 529 responses, individual metric errors, or client-side processing failures? Please share environment identifiers privately through the support case.

Please start with one representative request/response and the expected-versus-returned dimension combinations, if known. Remove authorization headers, access tokens, and other credentials.

References

• Metrics Batch — Batch
• Migrate to the Metrics Batch API - dated 01/23/2025, older than six months; rechecked during this review.

Hope this helps. and please feel free to reach out if you have any further questions. Thank you