Skip to main content

​
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

MethodPathSummaryAuthStabilityPermissions
GET/api/forecastGenerate demand forecastssessionstableforecast.read
GET/api/forecast/change-historyGet forecast change historysessionstableforecast.read
GET/api/forecast/channel-projectionGet channel-level projectionssessionstableforecast.read
GET/api/forecast/eventsList external eventssessionstableforecast.read
POST/api/forecast/eventsCreate an external eventsessionstableforecast.write
GET/api/forecast/events/[id]Get a specific eventsessionstableforecast.read
PUT/api/forecast/events/[id]Update an eventsessionstableforecast.write
DELETE/api/forecast/events/[id]Delete an eventsessionstableforecast.write
GET/api/forecast/long-termGet long-term forecastsessionstableforecast.read
GET/api/forecast/scenariosList forecast scenariossessionstableforecast.read
POST/api/forecast/scenariosCreate a new forecast scenariosessionstableforecast.write
GET/api/forecast/scenarios/[id]Get a specific scenariosessionstableforecast.read
PUT/api/forecast/scenarios/[id]Update a scenariosessionstableforecast.write
DELETE/api/forecast/scenarios/[id]Archive a scenariosessionstableforecast.write
POST/api/forecast/scenarios/[id]/generateGenerate forecasts for a scenariosessionstableforecast.write
POST/api/forecast/scenarios/[id]/publishPublish a scenariosessionstableforecast.write
POST/api/forecast/scenarios/compareCompare multiple scenariossessionstableforecast.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
}

​
Permissions & Roles

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