Better Data

API Reference

Forecasting API

Edit this page

Forecasting API

The Forecasting API provides endpoints for managing forecast scenarios, external events, accuracy metrics, and channel projections.

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Authentication

All requests require authentication. Include your API key in the Authorization header:

1Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Base URL

1https://app.betterdata.co/api/forecast

Headers

All requests must include:

1Content-Type: application/json
2Authorization: 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

1curl -X GET "https://app.betterdata.co/api/forecast/scenarios?status=PUBLISHED&type=BASELINE" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json"

Response:

1{
2  "scenarios": [
3    {
4      "id": "scenario_123",
5      "name": "Q1 2024 Baseline",
6      "description": "Baseline forecast for Q1 2024",
7      "type": "BASELINE",
8      "status": "PUBLISHED",
9      "createdAt": "2024-01-01T00:00:00Z",
10      "updatedAt": "2024-01-15T00:00:00Z"
11    }
12  ]
13}

Create Forecast Scenario

1curl -X POST "https://app.betterdata.co/api/forecast/scenarios" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Q2 2024 Promotional",
6    "description": "Forecast with promotional events",
7    "type": "PROMOTIONAL",
8    "assumptions": {
9      "narrative": "Q2 includes major promotional campaign",
10      "globalLiftPct": 0.15,
11      "includedEventIds": ["event_123", "event_456"]
12    }
13  }'

Response:

1{
2  "scenario": {
3    "id": "scenario_456",
4    "name": "Q2 2024 Promotional",
5    "description": "Forecast with promotional events",
6    "type": "PROMOTIONAL",
7    "status": "DRAFT",
8    "createdAt": "2024-03-01T00:00:00Z"
9  }
10}

Create External Event

1curl -X POST "https://app.betterdata.co/api/forecast/events" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Summer Sale 2024",
6    "type": "PROMOTION",
7    "startsAt": "2024-06-01T00:00:00Z",
8    "endsAt": "2024-06-30T23:59:59Z",
9    "value": {
10      "liftPct": 0.25,
11      "stackingMode": "MULTIPLICATIVE",
12      "description": "25% lift during summer sale"
13    },
14    "productMasterId": "prod_123"
15  }'

Response:

1{
2  "id": "event_789",
3  "name": "Summer Sale 2024",
4  "type": "PROMOTION",
5  "startsAt": "2024-06-01T00:00:00Z",
6  "endsAt": "2024-06-30T23:59:59Z",
7  "value": {
8    "liftPct": 0.25,
9    "stackingMode": "MULTIPLICATIVE"
10  },
11  "isGlobal": false,
12  "isOrgWide": true,
13  "productMaster": {
14    "id": "prod_123",
15    "name": "Product Name",
16    "sku": "SKU-123"
17  },
18  "createdAt": "2024-03-15T00:00:00Z"
19}

Common Errors

401 Unauthorized

1{
2  "error": "Unauthorized"
3}

Cause: Missing or invalid API key.

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

403 Forbidden

1{
2  "error": "Feature not enabled",
3  "code": "FEATURE_NOT_ENABLED",
4  "feature": "Demand Forecasting",
5  "planCapability": "ai.forecasting.demand"
6}

Example error shape; exact field names may vary by API version.

Cause: Forecasting feature not enabled for your organization.

Solution: Contact your organization administrator to enable the forecasting feature.

400 Bad Request

1{
2  "error": "Validation error",
3  "details": {
4    "name": ["Required"],
5    "type": ["Invalid enum value"]
6  }
7}

Cause: Invalid request parameters.

Solution: Review the request body and ensure all required fields are provided with valid values.

404 Not Found

1{
2  "error": "Scenario not found"
3}

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

1{
2  id: string;
3  name: string;
4  description?: string;
5  type: "BASELINE" | "PROMOTIONAL" | "CONSERVATIVE" | "OPTIMISTIC" | "CHANNEL_LAUNCH" | "CUSTOM";
6  status: "DRAFT" | "PUBLISHED" | "ARCHIVED";
7  assumptions?: {
8    narrative?: string;
9    globalLiftPct?: number; "cmt">// -1 to 5
10    categoryAdjustments?: Array<{
11      categoryId: string;
12      liftPct: number;
13    }>;
14    channelAdjustments?: Array<{
15      channelId: string;
16      liftPct: number;
17    }>;
18    includedEventIds?: string[];
19  };
20  createdAt: string; "cmt">// ISO datetime
21  updatedAt: string; "cmt">// ISO datetime
22}

External Event

1{
2  id: string;
3  name: string;
4  type: "PROMOTION" | "PRICE_CHANGE" | "HOLIDAY" | "WEATHER" | "BOOKING" | "MACRO" | "OTHER";
5  startsAt: string; "cmt">// ISO datetime
6  endsAt: string; "cmt">// ISO datetime
7  value?: {
8    liftPct?: number; "cmt">// -0.99 to 5
9    stackingMode?: "MULTIPLICATIVE" | "ADDITIVE";
10    description?: string;
11  };
12  isGlobal: boolean;
13  isOrgWide: boolean;
14  productMaster?: {
15    id: string;
16    name: string;
17    sku: string;
18  };
19  location?: {
20    id: string;
21    name: string;
22    code?: string;
23  };
24  createdAt: string; "cmt">// ISO datetime
25}

Permissions & Roles

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

Scenarios

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Endpoints

List Scenarios

GET /api/forecast/scenarios

See the OpenAPI bundle for endpoint-level details.

Create Scenario

POST /api/forecast/scenarios

See the OpenAPI bundle for endpoint-level details.

Get Scenario

GET /api/forecast/scenarios/{id}

See the OpenAPI bundle for endpoint-level details.

Update Scenario

PATCH /api/forecast/scenarios/{id}

See the OpenAPI bundle for endpoint-level details.

Generate Forecast

POST /api/forecast/scenarios/{id}/generate

See the OpenAPI bundle for endpoint-level details.

Publish Scenario

POST /api/forecast/scenarios/{id}/publish

See the OpenAPI bundle for endpoint-level details.

Permissions & Roles

Creating and publishing scenarios requires planning permissions. Viewing scenarios requires standard user permissions.

Events

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Endpoints

List Events

GET /api/forecast/events

See the OpenAPI bundle for endpoint-level details.

Create Event

POST /api/forecast/events

See the OpenAPI bundle for endpoint-level details.

Get Event

GET /api/forecast/events/{id}

See the OpenAPI bundle for endpoint-level details.

Update Event

PATCH /api/forecast/events/{id}

See the OpenAPI bundle for endpoint-level details.

Delete Event

DELETE /api/forecast/events/{id}

See the OpenAPI bundle for endpoint-level details.

Permissions & Roles

Creating and managing events requires planning permissions. Viewing events requires standard user permissions.

Accuracy

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Endpoints

Get Accuracy Metrics

GET /api/forecast/accuracy

See the OpenAPI bundle for endpoint-level details.

Change History

GET /api/forecast/change-history

See the OpenAPI bundle for endpoint-level details.

Permissions & Roles

Viewing forecast accuracy requires standard user permissions. All accuracy metrics are scoped to your organization.

Projections

Scope: Workspace-scoped — requires authenticated organization context and valid credentials for that workspace.

Endpoints

Channel Projections

GET /api/forecast/channel-projection

See the OpenAPI bundle for endpoint-level details.

Long-Term Forecast

GET /api/forecast/long-term

See the OpenAPI bundle for endpoint-level details.

Permissions & Roles

Viewing projections requires standard user permissions. All projections are scoped to your organization.