references/cost-query/request-body-schema.md
Cost Query Tool Contract
query_costs accepts typed MCP parameters. Use this contract for MCP calls; an
API fallback must use the official Cost Management Query API schema instead of
translating arbitrary fields.
| Parameter | Required | Values or format |
|---|---|---|
| scope | Yes | Azure scope path; never a tenant ID |
| timeframe | No | MonthToDate, BillingMonthToDate, TheLastMonth, TheLastBillingMonth, WeekToDate, TheCurrentMonth, Custom |
| from, to | Together | YYYY-MM-DD; supplying both selects Custom |
| granularity | No | None (default), Daily, Monthly |
| groupBy | No | Up to five comma-separated dimensions |
| filterDimension | With filterValues | One supported dimension |
| filterValues | With filterDimension | Comma-separated exact values; upstream operator is In |
| metric | No | PreTaxCost (default), Cost, AmortizedCost |
| sortBy | No | Cost column or selected grouping dimension |
| sortDirection | No | desc (default), asc, descending, ascending |
| top | No | 1-5000; default 100 |
The server creates the aggregation, grouping, filter, and sorting payload. Callers cannot supply compound filters, tag filters, arbitrary aggregation columns, request-body fields, or continuation URLs.
The structured response preserves the upstream columns and rows. Read each
row using the corresponding column index rather than assuming a fixed order.