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

Scenario	System Behavior
No time period specified	Defaults to current month start → today.
from is after to	System silently swaps from and to.

Future Date Handling

Scenario	System Behavior
Both from and to are in the future	Entire period shifted to the equivalent period last year.
Only to is in the future	to is adjusted to today's date.

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

Granularity-Based Range Limits

Granularity	Maximum Range	Truncation Behavior
Daily	31 days	from truncated to to - 1 month + 1 day.
Monthly	12 months	from truncated to to - 12 months + 1 day.
None	12 months	from truncated to to - 12 months + 1 day.

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

Minimum Start Date

Constraint	Value
Earliest allowed from date	May 1, 2014

GroupBy Interaction with Time Period

Combination	System Behavior
GroupBy + Daily granularity	Time period adjusted to the last day of the requested range.
GroupBy + Monthly granularity	Time period adjusted to the last month of the requested range.

💡 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.

Scope	ResourceId GroupBy
Subscription	✅ Supported
Resource Group	✅ Supported
Billing Account	❌ Not supported
Management Group	❌ Not supported
Billing Profile	❌ Not supported
Department (EA)	❌ Not supported
Enrollment Account (EA)	❌ Not supported
Invoice Section (MCA)	❌ Not supported
Customer (Partner)	❌ Not supported

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

Rule	Limit	Error Behavior
Maximum GroupBy dimensions	2	Validation error if more than 2 specified.
Duplicate columns in GroupBy	Not allowed	Validation error on duplicate column names.
Same column in Aggregation and GroupBy	Not allowed	Validation error if a column appears in both.

Aggregation Constraints

Rule	Details
Standard queries aggregation function	Only Sum is allowed.
Date in aggregation with granularity	Not allowed. Cannot aggregate on Date when granularity is Daily or Monthly.

Filter Constraints

Rule	Details
and operator	Must have 2 or more child expressions.
or operator	Must have 2 or more child expressions.
not operator	Must have exactly 1 child expression.

⚠️ 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.

Agreement Type	Unique Dimensions	Reference
EA	DepartmentName, EnrollmentAccountName, BillingPeriod	See dimensions-by-scope.md
MCA	InvoiceSectionName	See dimensions-by-scope.md
MOSP	(common dimensions only)	See dimensions-by-scope.md

Validation	Error Behavior
Dimension not valid for agreement type	BillingSubscriptionNotFound or dimension validation error.
Dimension not valid for scope type	BadRequest with invalid dimension message.

⚠️ 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

Scenario	Result
Filter by SubscriptionName without SubscriptionId at Management Group scope	Error returned.
Error message	"To view cost data, the subscription ID is needed. Select Subscriptions to find the ID for your subscription, and then ask your question again."

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",