1# Cost Forecast Workflow
2 
3Use this workflow when the user wants to **project future costs**.
4 
5> ⚠️ **Warning:** If the user wants **historical** cost data, use the [Cost Query Workflow](../cost-query/workflow.md). If they want to **reduce** costs, use the [Cost Optimization Workflow](../cost-optimization/workflow.md).
6 
7## Key Differences from Query API
8 
9| Aspect | Query API | Forecast API |
10|--------|-----------|--------------|
11| Purpose | Historical cost data | Projected future costs |
12| Time period | Past dates only | Must include future dates |
13| Grouping | Up to 2 dimensions | **Not supported** |
14| `includeActualCost` | N/A | Include historical alongside forecast |
15| Response columns | Cost, Date, Currency | Cost, Date, **CostStatus**, Currency |
16| Max response rows | 5,000/page | 40 rows recommended |
17| Timeframe | Multiple presets + Custom | Typically `Custom` only |
18 
19## Step 1: Determine Scope
20 
21Use the same scope patterns from the Scope Reference table in the main [SKILL.md](../SKILL.md#scope-reference-shared-across-all-workflows).
22 
23## Step 2: Choose Report Type
24 
25`ActualCost` is most common for forecasting. `AmortizedCost` for reservation/savings plan projections.
26 
27## Step 3: Set Time Period
28 
29> ⚠️ **Warning:** The `to` date **MUST** be in the future.
30 
31- Set `timeframe` to `Custom` and provide `timePeriod` with `from` and `to` dates
32- `from` can be in the past — shows actual costs up to today, then forecast to `to`
33- Minimum 28 days of historical cost data required
34- Maximum forecast period: 10 years
35 
36> **Full rules:** [Forecast Guardrails](./guardrails.md)
37 
38## Step 4: Configure Dataset
39 
40- **Granularity**: `Daily` or `Monthly` recommended
41- **Aggregation**: Typically `Sum` of `Cost`
42- See [Forecast Request Body Schema](./request-body-schema.md) for full schema
43 
44> ⚠️ **Warning:** Grouping is **NOT supported** for forecast. Suggest using the [Cost Query Workflow](../cost-query/workflow.md) for grouped historical data instead.
45 
46## Step 5: Set Forecast-Specific Options
47 
48| Field | Default | Description |
49|-------|---------|-------------|
50| `includeActualCost` | `true` | Include historical actual costs alongside forecast |
51| `includeFreshPartialCost` | `true` | Include partial cost data for recent days. **Requires `includeActualCost: true`** |
52 
53## Step 6: Construct and Execute
54 
55**Create `temp/cost-forecast.json`:**
56```json
57{
58  "type": "ActualCost",
59  "timeframe": "Custom",
60  "timePeriod": {
61    "from": "<first-of-month>",
62    "to": "<last-of-month>"
63  },
64  "dataset": {
65    "granularity": "Daily",
66    "aggregation": {
67      "totalCost": { "name": "Cost", "function": "Sum" }
68    },
69    "sorting": [{ "direction": "Ascending", "name": "UsageDate" }]
70  },
71  "includeActualCost": true,
72  "includeFreshPartialCost": true
73}
74```
75 
76**Execute:**
77```powershell
78New-Item -ItemType Directory -Path "temp" -Force
79 
80az rest --method post `
81  --url "/subscriptions/<subscription-id>/providers/Microsoft.CostManagement/forecast?api-version=2023-11-01" `
82  --headers "ClientType=GitHubCopilotForAzure" `
83  --body '@temp/cost-forecast.json'
84```
85 
86## Step 7: Interpret Response
87 
88| CostStatus | Meaning |
89|------------|---------|
90| `Actual` | Historical actual cost (when `includeActualCost: true`) |
91| `Forecast` | Projected future cost |
92 
93> 💡 **Tip:** "Forecast is unavailable for the specified time period" is not an error — it means the scope has insufficient historical data. Suggest using the [Cost Query Workflow](../cost-query/workflow.md) for available data.
94 
95## Key Guardrails
96 
97| Rule | Constraint |
98|------|-----------|
99| `to` date | Must be in the future |
100| Grouping | Not supported |
101| Min training data | 28 days of historical cost data |
102| Max forecast period | 10 years |
103| Response row limit | 40 rows recommended |
104| `includeFreshPartialCost` | Requires `includeActualCost: true` |
105| Monthly + includeActualCost | Requires explicit `timePeriod` |
106 
107> **Full details:** [Forecast Guardrails](./guardrails.md)
108 
109## Error Handling
110 
111| Status | Error | Remediation |
112|--------|-------|-------------|
113| 400 | Can't forecast on the past | Ensure `to` date is in the future. |
114| 400 | Missing dataset | Add required `dataset` field. |
115| 400 | Invalid dependency | Set `includeActualCost: true` when using `includeFreshPartialCost`. |
116| 403 | Forbidden | Needs **Cost Management Reader** role on scope. |
117| 424 | Bad training data | Insufficient history; falls back to actual costs if available. |
118| 429 | Rate limited | Check all `x-ms-ratelimit-microsoft.costmanagement-*-retry-after` headers (`qpu`, `entity`, `tenant`). Wait for the **longest** value. **Max 3 retries.** |
119| 503 | Service unavailable | Check [Azure Status](https://status.azure.com). |
120 
121> **Full details:** [Forecast Error Handling](./error-handling.md)
122 
123For more forecast examples, see [forecast examples](./examples.md).
124