Azure Cost Governance

Azure Cost Governance

Shared Workflow Routing

• Use the shared workflow spec for deterministic multi-plugin routing: workflows/multi-plugin-workflows.md.
• Apply the trigger phrases, handoff contracts, auth prerequisites, validation checkpoints, and stop conditions before escalating to the next plugin.

This skill provides comprehensive FinOps guidance via the Azure Cost Management and Consumption REST APIs — cost queries, budgets, forecasts, idle resource detection, and savings recommendations with risk-ranked actions and rollback notes.

Integration Context Contract

• Canonical contract: docs/integration-context.md

* Use sovereign cloud values from the canonical contract when applicable.

Fail fast before API calls when required context is missing or invalid. Redact tenant/subscription/object IDs in outputs.

Base URLs

Cost Management:  https://management.azure.com/{scope}/providers/Microsoft.CostManagement
Consumption:      https://management.azure.com/{scope}/providers/Microsoft.Consumption

API Endpoints

Cost Management (Microsoft.CostManagement)

Consumption (Microsoft.Consumption)

Query API

Request Body Schema

POST /{scope}/providers/Microsoft.CostManagement/query?api-version=2025-03-01
{
  "type": "ActualCost",
  "timeframe": "MonthToDate",
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": {
        "name": "PreTaxCost",
        "function": "Sum"
      }
    },
    "grouping": [
      {
        "name": "ServiceName",
        "type": "Dimension"
      }
    ],
    "filter": {
      "dimensions": {
        "name": "ResourceGroup",
        "operator": "In",
        "values": ["rg-production", "rg-staging"]
      }
    }
  }
}

Query Type Values

Timeframe Values

Custom Time Period

{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "2026-01-01T00:00:00Z",
    "to": "2026-01-31T23:59:59Z"
  },
  "dataset": { ... }
}

Dataset Options

• granularity: Daily or Monthly
• aggregation: up to 2 clauses, only Sum function. Columns: PreTaxCost, Cost, CostUSD, PreTaxCostUSD
• grouping: up to 2 clauses, type is Dimension or TagKey
• filter: nested structure with and[], or[], dimensions, tags

Filter Structure

{
  "filter": {
    "and": [
      {
        "dimensions": {
          "name": "ResourceGroup",
          "operator": "In",
          "values": ["rg-production"]
        }
      },
      {
        "tags": {
          "name": "Environment",
          "operator": "In",
          "values": ["Production"]
        }
      }
    ]
  }
}

Pagination

Response includes properties.nextLink when more pages exist. POST the same body to the full nextLink URL (contains $skiptoken) until nextLink is null.

Budgets API

Create/Update Budget

PUT /{scope}/providers/Microsoft.Consumption/budgets/{budgetName}?api-version=2024-08-01
{
  "properties": {
    "category": "Cost",
    "amount": 5000,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2026-03-01T00:00:00Z",
      "endDate": "2027-02-28T00:00:00Z"
    },
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceGroupName",
            "operator": "In",
            "values": ["rg-production"]
          }
        }
      ]
    },
    "notifications": {
      "actual_GreaterThan_80_Percent": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 80,
        "thresholdType": "Actual",
        "contactEmails": ["finops@contoso.com"],
        "contactRoles": ["Owner", "Contributor"],
        "contactGroups": [],
        "locale": "en-us"
      },
      "forecasted_GreaterThan_100_Percent": {
        "enabled": true,
        "operator": "GreaterThan",
        "threshold": 100,
        "thresholdType": "Forecasted",
        "contactEmails": ["finops@contoso.com"],
        "contactRoles": ["Owner"]
      }
    }
  }
}

Budget Properties

Up to 5 notification rules per budget.

Forecast API

POST /{scope}/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
  "type": "ActualCost",
  "timeframe": "Custom",
  "timePeriod": {
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-31T23:59:59Z"
  },
  "dataset": {
    "granularity": "Daily",
    "aggregation": {
      "totalCost": {
        "name": "Cost",
        "function": "Sum"
      }
    }
  },
  "includeActualCost": true,
  "includeFreshPartialCost": true
}

Notes:

• timeframe must be Custom for forecast
• granularity must be Daily
• includeActualCost: true merges already-accrued actuals with forecast rows
• Requires at least 1 week of historical data; returns 424 FailedDependency if insufficient

Usage Details (OData Filters)

GET /{scope}/providers/Microsoft.Consumption/usageDetails?api-version=2024-08-01
  &$filter=properties/resourceGroup eq 'rg-production' and properties/usageStart ge '2026-02-01'
  &$top=1000
  &metric=ActualCost

Note: This API is deprecated. Use generateCostDetailsReport for new implementations.

Scope Reference

Dimension Reference

Common dimension names for grouping and filter:

Resource Dimensions

Service Dimensions

Billing Dimensions

Tag Dimensions

Use type: "TagKey" in grouping. Use filter.tags for tag-based filtering.

Common FinOps Patterns

Pattern 1: Monthly Cost Breakdown by Service

1. POST /{scope}/providers/Microsoft.CostManagement/query with type: ActualCost, timeframe: TheLastMonth, grouping by ServiceName
2. Sort results by cost descending
3. Identify top 5 cost drivers
4. Compare with previous month using Custom timeframe
5. Flag services with >20% month-over-month growth

Pattern 2: Budget Health Check

1. GET /{scope}/providers/Microsoft.Consumption/budgets — list all budgets
2. For each budget: calculate currentSpend / amount * 100 to get utilization percentage
3. POST .../forecast — forecast remaining month spend
4. If forecast exceeds budget: flag with projected overrun amount
5. Generate alert recommendations for budgets missing forecasted thresholds

Pattern 3: Idle Resource Detection

1. Query cost by ResourceId for the last 30 days — identify resources with near-zero cost
2. Cross-reference with Azure Advisor recommendations for right-sizing
3. Check for: unattached disks, stopped VMs with premium disks, idle load balancers, unused public IPs
4. Estimate monthly savings per idle resource
5. Classify by reversibility: safe to stop (VMs), safe to delete (unattached disks), needs review (load balancers)

Pattern 4: Tag Compliance Audit

1. Query cost grouped by a required tag (e.g., CostCenter) — identify untagged spend
2. POST .../query with filter for resources missing the tag
3. Calculate percentage of total spend that is untagged
4. Identify top untagged resource groups for remediation
5. Produce tag compliance report with untagged cost by resource group

Pattern 5: Reservation Utilization Review

1. POST .../query with type: AmortizedCost to see reservation amortization
2. Compare amortized cost vs on-demand equivalent
3. Identify underutilized reservations (amortized cost > actual usage)
4. Recommend reservation modifications or exchanges
5. Calculate net savings from reservation portfolio

Required Permissions

EA-specific roles: Enterprise Administrator, Enterprise Read-Only, Department Administrator (requires DA view charges enabled), Account Owner (requires AO view charges enabled).

Error Handling

Throttle Handling

For 429 responses, read the x-ms-ratelimit-microsoft.consumption-retry-after or Retry-After header and wait before retrying:

if (response.status === 429) {
  const retryAfter = parseInt(response.headers["retry-after"] || "300", 10);
  await new Promise(r => setTimeout(r, retryAfter * 1000));
}

Azure CLI Reference

The Azure CLI provides direct command-line access to cost management and consumption APIs. The commands below complement the REST API patterns above.

Prerequisites

# Sign in and set active subscription
az login
az account set --subscription "<sub-id>"

# Verify required extensions are installed
az extension add --name costmanagement --upgrade
az extension add --name resource-graph --upgrade

Budget Management (az consumption budget)

# Create a resource-group-scoped budget
az consumption budget create --budget-name "<name>" --resource-group <rg> \
  --amount 1000 --time-grain Monthly \
  --start-date 2026-01-01 --end-date 2026-12-31 --category Cost

# Create budget with notification thresholds
az consumption budget create --budget-name "<name>" --resource-group <rg> \
  --amount 5000 --time-grain Monthly \
  --start-date 2026-01-01 --end-date 2026-12-31 --category Cost \
  --notifications "{\"Actual_GreaterThan_80_Percent\":{\"enabled\":true,\"operator\":\"GreaterThan\",\"threshold\":80,\"contactEmails\":[\"admin@contoso.com\"],\"contactRoles\":[\"Owner\"]}}"

# Subscription-level budget (omit --resource-group)
az consumption budget create --budget-name "<name>" \
  --amount 10000 --time-grain Monthly \
  --start-date 2026-01-01 --end-date 2026-12-31 --category Cost

# List budgets
az consumption budget list --output table
az consumption budget list --resource-group <rg> --output table

# Show / delete budget
az consumption budget show --budget-name "<name>"
az consumption budget show --budget-name "<name>" --resource-group <rg>
az consumption budget delete --budget-name "<name>"

Usage Details (az consumption usage)

# Current billing period (top 50 rows)
az consumption usage list --top 50 --output table

# Specific date range
az consumption usage list --start-date 2026-01-01 --end-date 2026-01-31 --output table

# Usage by resource group with JMESPath projection
az consumption usage list --resource-group <rg> --top 100 \
  --query "[].{Resource:instanceName, Cost:pretaxCost, Currency:currency}" --output table

Cost Management Queries (az costmanagement query)

# Costs by resource group — current month
az costmanagement query --type ActualCost --timeframe MonthToDate \
  --scope "subscriptions/<sub-id>" \
  --dataset-grouping name=ResourceGroup type=Dimension --output table

# Costs by service — custom date range
az costmanagement query --type ActualCost --timeframe Custom \
  --time-period from=2026-02-01 to=2026-03-01 \
  --scope "subscriptions/<sub-id>" \
  --dataset-grouping name=ServiceName type=Dimension --output table

# Amortized cost by resource — month to date
az costmanagement query --type AmortizedCost --timeframe MonthToDate \
  --scope "subscriptions/<sub-id>" \
  --dataset-grouping name=ResourceId type=Dimension --output table

Cost Exports (az costmanagement export)

# Create a daily scheduled export to Storage
az costmanagement export create --name "<export-name>" \
  --scope "subscriptions/<sub-id>" \
  --storage-account-id "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<sa>" \
  --storage-container exports --timeframe MonthToDate --type ActualCost \
  --schedule-recurrence Daily --schedule-status Active \
  --storage-directory "cost-reports"

# List / show / run / delete exports
az costmanagement export list --scope "subscriptions/<sub-id>" --output table
az costmanagement export show --name "<export-name>" --scope "subscriptions/<sub-id>"
az costmanagement export execute --name "<export-name>" --scope "subscriptions/<sub-id>"
az costmanagement export delete --name "<export-name>" --scope "subscriptions/<sub-id>" --yes

Azure Advisor Cost Recommendations

# List cost recommendations
az advisor recommendation list --category Cost --output table

# Detailed view with savings estimates
az advisor recommendation list --category Cost \
  --query "[].{Impact:impact, Problem:shortDescription.problem, Solution:shortDescription.solution, Savings:extendedProperties.annualSavingsAmount}" \
  --output table

# Refresh recommendations with lower CPU threshold
az advisor configuration update --low-cpu-threshold 5

Resource Graph — Idle Resource Detection

# Unattached managed disks
az graph query -q "Resources | where type == 'microsoft.compute/disks' | where properties.diskState == 'Unattached' | project name, resourceGroup, sku.name, properties.diskSizeGB, location" --output table

# Deallocated VMs (still incurring disk costs)
az graph query -q "Resources | where type == 'microsoft.compute/virtualMachines' | where properties.extended.instanceView.powerState.code == 'PowerState/deallocated' | project name, resourceGroup, location" --output table

# Empty App Service Plans (no hosted apps)
az graph query -q "Resources | where type == 'microsoft.web/serverfarms' | where properties.numberOfSites == 0 | project name, resourceGroup, sku.name, location" --output table

# Public IPs with no association
az graph query -q "Resources | where type == 'microsoft.network/publicipaddresses' | where isnull(properties.ipConfiguration) | project name, resourceGroup, properties.ipAddress, location" --output table

Reservation Recommendations and Utilization

# Reservation recommendations (shared scope, 30-day lookback)
az consumption reservation recommendation list --scope Shared --look-back-period Last30Days --output table

# Reservation usage details
az consumption reservation detail list --reservation-order-id <order-id> \
  --start-date 2026-01-01 --end-date 2026-01-31 --output table

# Reservation utilization summaries (daily grain)
az consumption reservation summary list --reservation-order-id <order-id> \
  --grain daily --start-date 2026-01-01 --end-date 2026-01-31 --output table

Decision Tree

1. Need to initialize scope/timeframe/currency/dimensions before analysis? → setup
2. Need spend breakdowns, groupings, filters, or reproducible query JSON? → azure-cost-query
3. Need budget utilization + forecast breach risk + interventions? → azure-budget-check
4. Need underutilization detection and reversible optimization actions? → azure-idle-resources
5. Request combines multiple goals? Run in order: setup → azure-cost-query/azure-budget-check → azure-idle-resources

Minimal References

• azure-cost-governance/commands/setup.md
• azure-cost-governance/commands/azure-cost-query.md
• azure-cost-governance/commands/azure-budget-check.md
• azure-cost-governance/commands/azure-idle-resources.md
• azure-cost-governance/README.md

Progressive Disclosure — Reference Files