Cost Query Workflow

Use this workflow when the user wants to understand their costs — breakdowns, trends, totals, top spenders.

Step 1: Determine Scope

Identify the Azure scope for the cost query from the Scope Reference table in the main SKILL.md.

Step 2: Choose Report Type

Step 3: Set Timeframe

Use a preset timeframe (e.g., MonthToDate, TheLastMonth, TheLastYear) or Custom with a timePeriod object.

⚠️ Warning: Key time period guardrails:

• Daily granularity: max 31 days
• Monthly/None granularity: max 12 months
• Custom timeframe requires a timePeriod object with from and to dates
• Future dates in historical queries are silently adjusted (see guardrails for details)

>

See guardrails.md for the complete set of validation rules.

Step 4: Configure Dataset

Define granularity, aggregation, grouping, filtering, and sorting in the dataset object.

• Granularity: None, Daily, or Monthly
• Aggregation: Use Sum on Cost or PreTaxCost for total cost
• Grouping: Up to 2 GroupBy dimensions (e.g., ServiceName, ResourceGroupName)
• Filtering: Use dimensions or tags filters with name, operator (In, Equal, Contains), and values fields
• Sorting: Order results by cost or dimension columns

💡 Tip: Not all dimensions are available at every scope. See dimensions-by-scope.md for the availability matrix.

For the full request body schema, see request-body-schema.md.

Step 5: Construct and Execute the API Call

Use az rest to call the Cost Management Query API.

Create cost query file:

Create temp/cost-query.json with:

{
  "type": "ActualCost",
  "timeframe": "MonthToDate",
  "dataset": {
    "granularity": "None",
    "aggregation": {
      "totalCost": {
        "name": "Cost",
        "function": "Sum"
      }
    },
    "grouping": [
      {
        "type": "Dimension",
        "name": "ServiceName"
      }
    ]
  }
}

Execute cost query:

# Create temp folder
New-Item -ItemType Directory -Path "temp" -Force

# Query using REST API (more reliable than az costmanagement query)
az rest --method post `
  --url "<scope>/providers/Microsoft.CostManagement/query?api-version=2023-11-01" `
  --headers "ClientType=GitHubCopilotForAzure" `
  --body '@temp/cost-query.json'

Step 6: Handle Pagination and Errors

• The API returns a maximum of 5,000 rows per page (default: 1,000).
• If nextLink is present in the response, follow it to retrieve additional pages.
• Handle rate limiting (HTTP 429) by checking all x-ms-ratelimit-microsoft.costmanagement-*-retry-after headers in the response. Wait for the longest value before retrying. Do not send further requests to the same scope until the retry-after duration has elapsed.

See error-handling.md for the full error reference.

Key Guardrails

Examples

Cost by service for the current month:

az rest --method post `
  --url "/subscriptions/<subscription-id>/providers/Microsoft.CostManagement/query?api-version=2023-11-01" `
  --headers "ClientType=GitHubCopilotForAzure" `
  --body '{
    "type": "ActualCost",
    "timeframe": "MonthToDate",
    "dataset": {
      "granularity": "None",
      "aggregation": {
        "totalCost": { "name": "Cost", "function": "Sum" }
      },
      "grouping": [
        { "type": "Dimension", "name": "ServiceName" }
      ]
    }
  }'

For more examples including daily trends, tag-based filtering, and multi-dimension queries, see examples.md.

Error Handling

See error-handling.md for detailed error handling including rate limit headers and retry strategies.