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 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

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

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:

{
  "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

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:

{
  "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

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:

{
  "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

{
  "error": "Unauthorized"
}

Cause: Missing or invalid API key.

Solution: Include a valid API key in the Authorization header.

403 Forbidden

{
  "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

{
  "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

{
  "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

{
  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

{
  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
• Authentication
• Common Errors

---

Permissions & Roles

Forecasting API access requires the ai.forecasting.demand entitlement. Contact your organization administrator to enable forecasting features.