Skip to content

Robertjam954/multimodal_rag_application / .claude/skills/azure-cost

azure-cost

Verified

Azure cost management: query costs, forecast spending, optimize to reduce waste. WHEN: "Azure costs", "Azure bill", "cost breakdown", "how much am I spending", "forecast spending", "optimize costs", "reduce spending", "orphaned resources", "rightsize VMs", "cost spike", "reduce storage costs", "AKS cost". DO NOT USE FOR: deploying resources, provisioning, diagnostics, or security audits.

cost-forecast/guardrails.md

View on GitHub
# Forecast API Guardrails

Detailed guardrails derived from CCM-LUX getForecastData and CCM-UX-MIDDLEWARE Forecaster.

## Time Period Validation

| Rule | Detail |
|---|---|
| `to` date must be in the future | `numberOfDaysToForecast` must be > 0. Entirely past date ranges return a `CantForecastOnThePast` error. |
| `from` can be in the past | When `from` is in the past, the response includes actual costs from `from` to today and forecast costs from today to `to`. |
| Both dates must be valid | When `timePeriod` is present, both `from` and `to` must be valid parseable ISO 8601 datetime strings. |
| Monthly + includeActualCost | Monthly granularity with `includeActualCost=true` requires an explicit `timePeriod` with valid `from` and `to` dates. Omitting it produces `DontContainsValidTimeRangeWhileMonthlyAndIncludeCost`. |
| Maximum forecast period | 10 years maximum forecast window. |

> ⚠️ **Warning:** If both `from` and `to` are in the past, the API returns `CantForecastOnThePast`. At least the `to` date must be in the future.

## Training Data Requirements

| Requirement | Value |
|---|---|
| Minimum historical data | 4 weeks (28 days) of cost data |
| Preferred training window | Up to 3 months of history |
| Late arrival tolerance | 2 days for billing data to arrive |
| New subscriptions (< 28 days) | Forecast unavailable |

> ⚠️ **Warning:** New subscriptions with fewer than 28 days of cost history cannot generate forecasts. Suggest using **the Cost Query workflow (Part 1)** to retrieve available historical data instead.

## Grouping Restriction

| Aspect | Detail |
|---|---|
| Grouping support | ❌ **Not supported** |
| API limitation | This is a hard limitation of the Forecast API. The `grouping` field is not accepted in the request body. |
| Workaround | If the user requests a grouped forecast (e.g., forecast by resource group or service), inform them that grouping is not supported for forecasts. Suggest querying historical data with grouping using **the Cost Query workflow (Part 1)** instead. |

> ⚠️ **Warning:** Even when using **the Cost Query workflow (Part 1)** for grouped historical data, `ResourceId` grouping is only supported at subscription scope and below. It is not supported at billing account, management group, or higher scopes.

## Response Row Limit

| Constraint | Detail |
|---|---|
| Maximum rows | 40 rows per forecast response |
| Daily example | 30 actual days + 30 forecast days = 60 rows → **exceeds limit** |
| Recommendation | For daily granularity, keep forecast period to ~2–3 weeks |
| Longer periods | Use monthly granularity to stay within the row limit |

> 💡 **Tip:** If the user needs a daily forecast for more than 2–3 weeks, consider splitting the request into smaller time windows or switching to monthly granularity.

## includeActualCost / includeFreshPartialCost

| Field | Default | Dependency |
|---|---|---|
| `includeActualCost` | `true` | None |
| `includeFreshPartialCost` | `true` | **Requires `includeActualCost=true`** |

> ⚠️ **Warning:** Setting `includeFreshPartialCost=true` without `includeActualCost=true` produces validation error `DontContainIncludeActualCostWhileIncludeFreshPartialCost`. Always set both fields explicitly.

## Forecast Availability

The API returns "Forecast is unavailable for the specified time period" when:

| Condition | Detail |
|---|---|
| Null/empty response rows | Response has no data rows |
| Insufficient training data | Scope has fewer than 28 days of cost history |
| No cost history | Scope has never had any cost data |

> ⚠️ **Warning:** This is **not an error** — it is a valid response indicating the forecast model cannot generate predictions. Do not retry. Instead, suggest using **the Cost Query workflow (Part 1)** to retrieve whatever historical data is available.

## Rate Limiting

### Rate Limit Thresholds

The Forecast API shares the same rate limits as the Cost Query API:

| Limit | Value |
|-------|-------|
| Per User | 20 requests per minute |
| Per Scope | 4 requests per minute |
| Per Tenant | 12 requests per 10 seconds, 60 requests per minute, 600 requests per hour |
| Per Client Type | 2,000 requests per minute |

> ⚠️ **Warning:** The **per-scope limit (4 requests/minute)** is the most restrictive. Sequential queries to the same subscription, resource group, or billing account share this limit.

### Rate Limit Headers

| Header | Description |
|---|---|
| `x-ms-ratelimit-microsoft.costmanagement-qpu-retry-after` | Seconds to wait before retrying (QPU-based) |
| `x-ms-ratelimit-microsoft.costmanagement-entity-retry-after` | Seconds to wait for entity/scope-level throttle |
| `x-ms-ratelimit-microsoft.costmanagement-tenant-retry-after` | Seconds to wait for tenant-level throttle |

### Handling 429 Responses

On a 429 response, check **all** retry-after headers present in the response. Multiple headers may be returned simultaneously. Take the **maximum** value and **do NOT retry until that duration has fully elapsed.**

> ⚠️ **Warning:** Do not retry before the retry-after duration has elapsed. Premature retries will be rejected and may extend the throttling period.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall