> ## Documentation Index > Fetch the complete documentation index at: https://betterdatainc.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Forecasting API > API reference for forecast scenarios, events, accuracy metrics, and channel projections # Forecasting API The Forecasting API provides endpoints for managing forecast scenarios, external events, accuracy metrics, and channel projections. **Scope**: Tenant-scoped; requires authenticated org context\ **Availability**: Not available in SuperAdmin ## Authentication All requests require authentication. Include your API key in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` See [Authentication](/api-reference/authentication) for details. ## Base URL ``` https://app.betterdata.co/api/forecast ``` ## Headers All requests must include: ``` Content-Type: application/json Authorization: Bearer YOUR_API_KEY ``` ## Endpoints {/* this block is generated; do not edit by hand */} | Method | Path | Summary | Auth | Stability | Permissions | | -------- | --------------------------------------- | --------------------------------- | ------- | --------- | -------------- | | `GET` | `/api/forecast` | Generate demand forecasts | session | stable | forecast.read | | `GET` | `/api/forecast/change-history` | Get forecast change history | session | stable | forecast.read | | `GET` | `/api/forecast/channel-projection` | Get channel-level projections | session | stable | forecast.read | | `GET` | `/api/forecast/events` | List external events | session | stable | forecast.read | | `POST` | `/api/forecast/events` | Create an external event | session | stable | forecast.write | | `GET` | `/api/forecast/events/[id]` | Get a specific event | session | stable | forecast.read | | `PUT` | `/api/forecast/events/[id]` | Update an event | session | stable | forecast.write | | `DELETE` | `/api/forecast/events/[id]` | Delete an event | session | stable | forecast.write | | `GET` | `/api/forecast/long-term` | Get long-term forecast | session | stable | forecast.read | | `GET` | `/api/forecast/scenarios` | List forecast scenarios | session | stable | forecast.read | | `POST` | `/api/forecast/scenarios` | Create a new forecast scenario | session | stable | forecast.write | | `GET` | `/api/forecast/scenarios/[id]` | Get a specific scenario | session | stable | forecast.read | | `PUT` | `/api/forecast/scenarios/[id]` | Update a scenario | session | stable | forecast.write | | `DELETE` | `/api/forecast/scenarios/[id]` | Archive a scenario | session | stable | forecast.write | | `POST` | `/api/forecast/scenarios/[id]/generate` | Generate forecasts for a scenario | session | stable | forecast.write | | `POST` | `/api/forecast/scenarios/[id]/publish` | Publish a scenario | session | stable | forecast.write | | `POST` | `/api/forecast/scenarios/compare` | Compare multiple scenarios | session | stable | forecast.read | ## Example Requests ### List Forecast Scenarios ```bash theme={null} curl -X GET "https://app.betterdata.co/api/forecast/scenarios?status=PUBLISHED&type=BASELINE" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" ``` **Response:** ```json theme={null} { "scenarios": [ { "id": "scenario_123", "name": "Q1 2024 Baseline", "description": "Baseline forecast for Q1 2024", "type": "BASELINE", "status": "PUBLISHED", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T00:00:00Z" } ] } ``` ### Create Forecast Scenario ```bash theme={null} curl -X POST "https://app.betterdata.co/api/forecast/scenarios" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Q2 2024 Promotional", "description": "Forecast with promotional events", "type": "PROMOTIONAL", "assumptions": { "narrative": "Q2 includes major promotional campaign", "globalLiftPct": 0.15, "includedEventIds": ["event_123", "event_456"] } }' ``` **Response:** ```json theme={null} { "scenario": { "id": "scenario_456", "name": "Q2 2024 Promotional", "description": "Forecast with promotional events", "type": "PROMOTIONAL", "status": "DRAFT", "createdAt": "2024-03-01T00:00:00Z" } } ``` ### Create External Event ```bash theme={null} curl -X POST "https://app.betterdata.co/api/forecast/events" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Summer Sale 2024", "type": "PROMOTION", "startsAt": "2024-06-01T00:00:00Z", "endsAt": "2024-06-30T23:59:59Z", "value": { "liftPct": 0.25, "stackingMode": "MULTIPLICATIVE", "description": "25% lift during summer sale" }, "productMasterId": "prod_123" }' ``` **Response:** ```json theme={null} { "id": "event_789", "name": "Summer Sale 2024", "type": "PROMOTION", "startsAt": "2024-06-01T00:00:00Z", "endsAt": "2024-06-30T23:59:59Z", "value": { "liftPct": 0.25, "stackingMode": "MULTIPLICATIVE" }, "isGlobal": false, "isOrgWide": true, "productMaster": { "id": "prod_123", "name": "Product Name", "sku": "SKU-123" }, "createdAt": "2024-03-15T00:00:00Z" } ``` ## Common Errors ### 401 Unauthorized ```json theme={null} { "error": "Unauthorized" } ``` **Cause**: Missing or invalid API key. **Solution**: Include a valid API key in the `Authorization` header. ### 403 Forbidden ```json theme={null} { "error": "Feature not enabled", "code": "FEATURE_NOT_ENABLED", "feature": "Demand Forecasting", "entitlement": "ai.forecasting.demand" } ``` **Cause**: Forecasting feature not enabled for your organization. **Solution**: Contact your organization administrator to enable the forecasting feature. ### 400 Bad Request ```json theme={null} { "error": "Validation error", "details": { "name": ["Required"], "type": ["Invalid enum value"] } } ``` **Cause**: Invalid request parameters. **Solution**: Review the request body and ensure all required fields are provided with valid values. ### 404 Not Found ```json theme={null} { "error": "Scenario not found" } ``` **Cause**: The requested scenario or event doesn't exist or isn't accessible. **Solution**: Verify the ID and ensure you have access to the resource. ## Query Parameters ### List Scenarios * `status`: Filter by status (`DRAFT`, `PUBLISHED`, `ARCHIVED`) * `type`: Filter by type (`BASELINE`, `PROMOTIONAL`, `CONSERVATIVE`, `OPTIMISTIC`, `CHANNEL_LAUNCH`, `CUSTOM`) * `includeArchived`: Include archived scenarios (boolean) ### List Events * `from`: Start date (ISO string, default: today) * `to`: End date (ISO string, default: +90 days) * `productMasterId`: Filter by product * `locationId`: Filter by location * `type`: Filter by event type * `includeGlobal`: Include global events (boolean, default: true) * `includeOrgWide`: Include org-wide events (boolean, default: true) ## Request/Response Schemas ### Scenario ```typescript theme={null} { id: string; name: string; description?: string; type: "BASELINE" | "PROMOTIONAL" | "CONSERVATIVE" | "OPTIMISTIC" | "CHANNEL_LAUNCH" | "CUSTOM"; status: "DRAFT" | "PUBLISHED" | "ARCHIVED"; assumptions?: { narrative?: string; globalLiftPct?: number; // -1 to 5 categoryAdjustments?: Array<{ categoryId: string; liftPct: number; }>; channelAdjustments?: Array<{ channelId: string; liftPct: number; }>; includedEventIds?: string[]; }; createdAt: string; // ISO datetime updatedAt: string; // ISO datetime } ``` ### External Event ```typescript theme={null} { id: string; name: string; type: "PROMOTION" | "PRICE_CHANGE" | "HOLIDAY" | "WEATHER" | "BOOKING" | "MACRO" | "OTHER"; startsAt: string; // ISO datetime endsAt: string; // ISO datetime value?: { liftPct?: number; // -0.99 to 5 stackingMode?: "MULTIPLICATIVE" | "ADDITIVE"; description?: string; }; isGlobal: boolean; isOrgWide: boolean; productMaster?: { id: string; name: string; sku: string; }; location?: { id: string; name: string; code?: string; }; createdAt: string; // ISO datetime } ``` *** ## Related Pages * [API Overview](/api-reference/overview) * [Authentication](/api-reference/authentication) * [Common Errors](/api-reference/errors) *** ## Permissions & Roles Forecasting API access requires the `ai.forecasting.demand` entitlement. Contact your organization administrator to enable forecasting features.