1# Cost Management Query API — Request Body Schema
2 
3Schema for the [Cost Management Query API](https://learn.microsoft.com/en-us/rest/api/cost-management/query/usage).
4 
5## Request Body Structure
6 
7```json
8{
9  "type": "<report-type>",
10  "timeframe": "<timeframe>",
11  "timePeriod": { "from": "2024-01-01T00:00:00Z", "to": "2024-01-31T23:59:59Z" },
12  "dataset": {
13    "granularity": "<granularity>",
14    "aggregation": { "<alias>": { "name": "<column>", "function": "<function>" } },
15    "grouping": [{ "type": "<column-type>", "name": "<column-name>" }],
16    "filter": { "<filter-expression>" },
17    "sorting": [{ "direction": "<direction>", "name": "<column>" }]
18  }
19}
20```
21 
22## Top-Level Fields
23 
24| Field | Type | Required | Description |
25|-------|------|----------|-------------|
26| `type` | string | Yes | `ActualCost`, `AmortizedCost`, or `Usage` |
27| `timeframe` | string | Yes | Predefined or `Custom` time window |
28| `timePeriod` | object | Conditional | Required when `timeframe` is `Custom`. Contains `from`/`to` ISO 8601 dates. |
29| `dataset` | object | Yes | Defines granularity, aggregation, grouping, filtering, sorting |
30 
31### Timeframe Values
32 
33`WeekToDate` · `MonthToDate` · `BillingMonthToDate` · `YearToDate` · `TheLastWeek` · `TheLastMonth` · `TheLastBillingMonth` · `TheLastYear` · `TheLast7Days` · `TheLast3Months` · `Custom`
34 
35## Dataset Fields
36 
37### Granularity
38 
39| Value | Max Range | Description |
40|-------|-----------|-------------|
41| `None` | 12 months | Aggregated total, no date breakdown |
42| `Daily` | 31 days | Day-by-day breakdown |
43| `Monthly` | 12 months | Month-by-month breakdown |
44 
45### Aggregation
46 
47```json
48"aggregation": { "totalCost": { "name": "Cost", "function": "Sum" } }
49```
50 
51| Field | Required | Description |
52|-------|----------|-------------|
53| `<alias>` (key) | Yes | Output column alias (e.g., `totalCost`) |
54| `name` | Yes | Source column: `Cost`, `PreTaxCost`, or `UsageQuantity` |
55| `function` | Yes | `Sum` (only supported function for cost queries) |
56 
57### Grouping
58 
59```json
60"grouping": [
61  { "type": "Dimension", "name": "ServiceName" },
62  { "type": "TagKey", "name": "Environment" }
63]
64```
65 
66- `type`: `Dimension` (built-in) or `TagKey` (resource tag)
67- Maximum **2** GroupBy dimensions per query. No duplicates.
68 
69### Filter
70 
71Filter expressions restrict which cost records are included. Filters support logical operators (`and`, `or`, `not`) and comparison operators on dimensions or tags.
72 
73#### Filter Expression Structure
74 
75```json
76"filter": {
77  "and": [
78    {
79      "dimensions": {
80        "name": "ResourceGroupName",
81        "operator": "In",
82        "values": ["rg-prod", "rg-staging"]
83      }
84    },
85    {
86      "not": {
87        "tags": {
88          "name": "Environment",
89          "operator": "Equal",
90          "values": ["dev"]
91        }
92      }
93    }
94  ]
95}
96```
97 
98#### Logical Operators
99 
100| Operator | Description | Children |
101|----------|-------------|----------|
102| `and` | All child expressions must match. | 2 or more expressions. |
103| `or` | Any child expression must match. | 2 or more expressions. |
104| `not` | Negates a single child expression. | Exactly 1 expression. |
105 
106> ⚠️ **Warning:** `and` and `or` must contain at least 2 child expressions. `not` must contain exactly 1.
107 
108#### Comparison Operators (ComparisonOperator Enum)
109 
110| Operator | Description | Example |
111|----------|-------------|---------|
112| `In` | Value is in the provided list. Supports multiple values. | `"values": ["vm", "storage"]` |
113| `Equal` | Exact match against a single value. | `"values": ["production"]` |
114| `Contains` | String contains the specified substring. | `"values": ["prod"]` |
115| `LessThan` | Numeric less-than comparison. | `"values": ["100"]` |
116| `GreaterThan` | Numeric greater-than comparison. | `"values": ["0"]` |
117| `NotEqual` | Value does not match the specified value. | `"values": ["dev"]` |
118 
119#### Filter Target Types
120 
121| Target | Description |
122|--------|-------------|
123| `dimensions` | Filter on built-in dimensions (e.g., `ResourceGroupName`, `ServiceName`). |
124| `tags` | Filter on Azure resource tags (e.g., `Environment`, `CostCenter`). |
125 
126### Sorting
127 
128```json
129"sorting": [
130  { "direction": "Descending", "name": "Cost" }
131]
132```
133 
134| Field | Type | Required | Description |
135|-------|------|----------|-------------|
136| `direction` | string | Yes | `Ascending` or `Descending`. |
137| `name` | string | Yes | Column name to sort by (must be present in aggregation or grouping). |
138 
139## Response Structure
140 
141```json
142{
143  "id": "<query-id>",
144  "name": "<query-name>",
145  "type": "Microsoft.CostManagement/query",
146  "properties": {
147    "nextLink": "<url-for-next-page-or-null>",
148    "columns": [
149      { "name": "Cost", "type": "Number" },
150      { "name": "ServiceName", "type": "String" },
151      { "name": "UsageDate", "type": "Number" },
152      { "name": "Currency", "type": "String" }
153    ],
154    "rows": [
155      [123.45, "Virtual Machines", 20240115, "USD"],
156      [67.89, "Storage", 20240115, "USD"]
157    ]
158  }
159}
160```
161 
162| Field | Type | Description |
163|-------|------|-------------|
164| `columns` | array | Array of column definitions with `name` and `type`. |
165| `columns[].name` | string | Column name. |
166| `columns[].type` | string | Data type: `Number` or `String`. |
167| `rows` | array | Array of row arrays. Values ordered to match `columns`. |
168| `nextLink` | string | URL for next page of results, or `null` if no more pages. |
169 
170> 💡 **Tip:** `UsageDate` is returned as a number in `YYYYMMDD` format (e.g., `20240115`) when granularity is `Daily` or `Monthly`.
171