Cost Query Guardrails

Detailed validation rules and guardrails for the Cost Management Query API. The system applies these automatically, but understanding them helps avoid unexpected query modifications or errors.

Time Period Validation

Default Behavior

Future Date Handling

⚠️ Warning: Future date shifting happens silently. The response data will cover the adjusted period, not the originally requested dates.

Granularity-Based Range Limits

⚠️ Warning: The absolute API limit is 37 months. Requests exceeding 37 months return HTTP 400 regardless of granularity.

Minimum Start Date

GroupBy Interaction with Time Period

💡 Tip: When using GroupBy with Daily granularity over a multi-day range, the system may return data only for the last day. For full daily breakdown with grouping, ensure the range is within the 31-day limit.

ResourceId Scope Restriction

⚠️ Warning: Grouping by ResourceId is only supported at subscription scope and below (subscription, resource group). It is NOT supported at higher scopes.

When the user requests a cost breakdown by resource at a billing account or management group scope, use ServiceName, SubscriptionName, or another supported dimension instead. If per-resource detail is needed, narrow the scope to a specific subscription first.

Dataset Validation

GroupBy Constraints

Aggregation Constraints

Filter Constraints

⚠️ Warning: A filter with a single child in and or or will fail validation. Wrap single-condition filters directly without a logical operator, or use not for negation.

Scope & Dimension Compatibility

Dimensions must be valid for the intersection of the agreement type and scope type.

⚠️ Warning: Using an EA-only dimension (e.g., DepartmentName) on a MOSP subscription will return a validation error. Always verify the agreement type before selecting dimensions.

EA + Management Group Special Case

Remediation: When filtering by subscription name at Management Group scope under EA, always include a SubscriptionId filter alongside the SubscriptionName filter.

{
  "and": [
    {
      "dimensions": {
        "name": "SubscriptionId",
        "operator": "In",
        "values": ["<subscription-id>"]
      }
    },
    {
      "dimensions": {
        "name": "SubscriptionName",
        "operator": "In",
        "values": ["My Subscription"]
      }
    }
  ]
}

Rate Limiting

Rate Limit Thresholds

⚠️ Warning: The per-scope limit (4 requests/minute) is the most restrictive. Sequential queries to the same subscription, resource group, or billing account share this limit.

QPU-Based Throttling

Rate Limit Headers

Handling 429 Responses

On a 429 response, check all retry-after headers present in the response. Multiple headers may be returned simultaneously. Take the maximum value and do NOT send any further requests to the same scope until that duration has fully elapsed.

⚠️ Warning: Do not retry before the retry-after duration has elapsed. Premature retries will be rejected and may extend the throttling period.

Pagination

💡 Tip: For large result sets, always check the nextLink field in the response. If present, make additional requests to retrieve all pages.