1# Forecast API Request Body Schema
2 
3## Complete JSON Schema
4 
5```json
6{
7  "type": "ActualCost",
8  "timeframe": "Custom",
9  "timePeriod": {
10    "from": "2024-01-01T00:00:00Z",
11    "to": "2024-03-31T00:00:00Z"
12  },
13  "dataset": {
14    "granularity": "Daily",
15    "aggregation": {
16      "totalCost": {
17        "name": "Cost",
18        "function": "Sum"
19      }
20    },
21    "sorting": [
22      {
23        "direction": "Ascending",
24        "name": "UsageDate"
25      }
26    ],
27    "filter": {
28      "dimensions": {
29        "name": "ResourceGroupName",
30        "operator": "In",
31        "values": ["my-resource-group"]
32      }
33    }
34  },
35  "includeActualCost": true,
36  "includeFreshPartialCost": true
37}
38```
39 
40## Field Reference
41 
42| Field | Type | Required | Values | Description |
43|---|---|---|---|---|
44| `type` | string | ✅ | `ActualCost`, `AmortizedCost`, `Usage` | Cost type for the forecast |
45| `timeframe` | string | ✅ | `Custom` | Must be `Custom` for forecast requests |
46| `timePeriod` | object | ✅ | — | Start and end dates for the forecast window |
47| `timePeriod.from` | string | ✅ | ISO 8601 datetime | Start date; can be in the past to include actuals |
48| `timePeriod.to` | string | ✅ | ISO 8601 datetime | End date; **must be in the future** for forecast |
49| `dataset` | object | ✅ | — | Dataset configuration for the forecast |
50| `dataset.granularity` | string | ✅ | `Daily`, `Monthly` | Time granularity of forecast results |
51| `dataset.aggregation` | object | ✅ | — | Aggregation functions to apply |
52| `dataset.aggregation.totalCost.name` | string | ✅ | `Cost` | Column name to aggregate |
53| `dataset.aggregation.totalCost.function` | string | ✅ | `Sum` | Aggregation function |
54| `dataset.sorting` | array | Optional | — | Sort order for results |
55| `dataset.sorting[].direction` | string | Optional | `Ascending`, `Descending` | Sort direction |
56| `dataset.sorting[].name` | string | Optional | `UsageDate` | Column to sort by |
57| `dataset.filter` | object | Optional | — | Filter expression (dimensions/tags) |
58| `includeActualCost` | boolean | Optional | `true`, `false` | Include historical actual costs alongside forecast. Default: `true` |
59| `includeFreshPartialCost` | boolean | Optional | `true`, `false` | Include partial cost data for recent days. Default: `true`. **Requires `includeActualCost=true`** |
60 
61## Forecast-Specific Fields
62 
63### `includeActualCost`
64 
65- **Type:** boolean
66- **Default:** `true`
67- When `true`, the response includes historical actual cost rows from the `from` date up to today, alongside projected forecast rows from today to the `to` date.
68- When `false`, only forecast (projected) rows are returned.
69 
70### `includeFreshPartialCost`
71 
72- **Type:** boolean
73- **Default:** `true`
74- When `true`, includes partial (incomplete) cost data for the most recent days where billing data is still arriving.
75- ⚠️ **Requires `includeActualCost=true`.** Setting `includeFreshPartialCost=true` without `includeActualCost=true` produces a validation error (`DontContainIncludeActualCostWhileIncludeFreshPartialCost`).
76 
77## Response Structure
78 
79### Response Columns
80 
81| Column | Type | Description |
82|---|---|---|
83| `Cost` | Number | The cost amount (actual or forecasted) |
84| `UsageDate` / `BillingMonth` | Datetime | The date for the cost row |
85| `CostStatus` | String | Indicates whether the row is historical or projected |
86| `Currency` | String | Currency code (e.g., `USD`, `EUR`) |
87 
88### CostStatus Values
89 
90| Value | Meaning |
91|---|---|
92| `Actual` | Historical cost data (already incurred) |
93| `Forecast` | Projected future cost (model prediction) |
94 
95### Granularity and Date Column Mapping
96 
97| Granularity | Date Column |
98|---|---|
99| `Daily` | `UsageDate` |
100| `Monthly` | `BillingMonth` |
101 
102## Key Differences from Query API Request Body
103 
104| Aspect | Forecast API | Query API |
105|---|---|---|
106| Grouping | ❌ Not supported | ✅ Supported via `grouping` field |
107| `timeframe` | Typically `Custom` only | Supports `Custom`, `MonthToDate`, `BillingMonthToDate`, etc. |
108| `includeActualCost` | ✅ Forecast-specific field | ❌ Not applicable |
109| `includeFreshPartialCost` | ✅ Forecast-specific field | ❌ Not applicable |
110| Response `CostStatus` column | ✅ Distinguishes `Actual` vs `Forecast` rows | ❌ Not present |
111| `to` date | Must be in the future | Can be any valid past/present date |
112