GETTING STARTED
Overview Quickstart
API REFERENCE
Endpoints Data Analysis Inventory Planning Product Insights Traffic Forecasting Batching Grouped Forecasting Patterns & Segmentation Rate Limiting
DASHBOARD
Entities Usage & Billing
EXAMPLES
Code Examples SDKs & Libraries
OPENAPI SPEC ↓
API REFERENCE

Traffic forecasting.

The traffic-forecasting endpoint turns a historical traffic series into an infrastructure plan. It forecasts future traffic for a single series. From the forecast it derives scaling recommendations, per-period capacity analysis, traffic alerts for spikes and anomalies, and a cost-optimization summary. These results tell you whether to scale, how much, and when.

Base URL
https://forecastapi.com/v2
Authentication
Bearer YOUR_API_KEY

Endpoint

Generate Traffic Plan POST /v2/traffic-forecasting

Supply your historical traffic series in data. Describe your current infrastructure and thresholds in traffic_settings. The API returns a full plan. The endpoint forecasts traffic automatically, so you do not call /forecast separately. The endpoint always runs the forecast with data_type set to "web_traffic". This value selects methods tuned for continuous, non-intermittent series.

Request Body

REQUEST POST /v2/traffic-forecasting 
{
  "identifier": "api-endpoint-users",
  "frequency": "H",
  "periods": 24,
  "data": [
    {"date": "2024-06-01 00:00:00", "value": 1200},
    {"date": "2024-06-01 01:00:00", "value": 850},
    {"date": "2024-06-01 02:00:00", "value": 620},
    {"date": "2024-06-01 03:00:00", "value": 480},
    {"date": "2024-06-01 04:00:00", "value": 520},
    {"date": "2024-06-01 05:00:00", "value": 780},
    {"date": "2024-06-01 06:00:00", "value": 1150},
    {"date": "2024-06-01 07:00:00", "value": 1680}
  ],
  "traffic_settings": {
    "current_capacity": 2000,
    "baseline_traffic": 1000,
    "scaling_buffer": 0.2,
    "scale_up_threshold": 0.8,
    "scale_down_threshold": 0.3,
    "alert_threshold": 1.5,
    "anomaly_threshold": 3.0,
    "cost_per_unit": 0.01,
    "fixed_cost_per_capacity": 0.10,
    "base_scaling_time": 5,
    "enable_auto_scaling": false
  }
}

Top-level Parameters

identifier STRING · REQUIRED
Unique identifier for the series (e.g., an endpoint, service, or app name). The response echoes it.
data ARRAY · REQUIRED
Historical traffic series. Each item needs a date (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS, consistent across the series) and a numeric value. The API sorts the series ascending automatically.
periods INTEGER · REQUIRED
Number of future periods to forecast (min 1). This value sets how far ahead scaling, capacity, and alerts look.
frequency STRING · REQUIRED
Series granularity: H, D, W, M, MS, ME, Q, or Y. It also sets each period's real-time duration for breach dates and alert timestamps (e.g. H = 60 min). Most traffic forecasts use H or D.
traffic_settings OBJECT · REQUIRED
Infrastructure position and thresholds. Two fields are required. The rest have defaults. See the table below.
start_date DATE · OPTIONAL
This field anchors all returned dates (breach date, alert timestamps). It defaults to the last date in data.
model STRING · DEFAULT standard
Forecasting model behind the plan: standard (default), advanced-quantized, advanced-patched, or auto. The auto option routes each identifier to the model that has proven most accurate on that series. It uses the same evidence that /forecast and /batch accumulate. On this endpoint the auto ensemble default runs as standard until a winning model emerges. See Model Options. Advanced variants and auto cost 25% more usage.
confidence_level FLOAT · DEFAULT 0.80
Confidence level for the forecast intervals in forecast_data (0.10–0.99). Default: 0.80.
selection_metric STRING · DEFAULT auto
Back-testing metric that picks the winning model: auto (default), combined, mase, or smape. The semantics match those on /forecast.
data_type STRING · OPTIONAL
The endpoint always sets this field to "web_traffic" and ignores any value you send.
tenant_context STRING · OPTIONAL
Optional multi-tenant scoping tag. The API uses it for stored-forecast attribution.

traffic_settings Object

Only current_capacity and baseline_traffic are required. Every other field is optional and uses the default shown. All values share the same unit as your traffic series (requests, users, or RPS — whatever you supply).

current_capacity NUMBER ≥ 1 · REQUIRED
The capacity you can serve today. This value drives utilization, scaling decisions, and cost.
baseline_traffic NUMBER ≥ 0 · REQUIRED
Your normal traffic level. It is the reference point for spike alerts (see alert_threshold).
scaling_buffer NUMBER 0–1 · DEFAULT 0.2
Headroom above the peak when the API sizes recommended capacity. A value of 0.2 sizes capacity to 120% of the forecast peak.
scale_up_threshold NUMBER 0–1 · DEFAULT 0.8
Utilization fraction (peak ÷ capacity). Above this fraction the API recommends a scale_up.
scale_down_threshold NUMBER 0–1 · DEFAULT 0.3
Utilization fraction. Below this fraction the API recommends a scale_down. Between the two thresholds the action is maintain.
alert_threshold NUMBER ≥ 1 · DEFAULT 1.5
Multiple of baseline_traffic that triggers a traffic_spike alert. A value of 1.5 alerts at 150% of baseline.
anomaly_threshold NUMBER ≥ 1 · DEFAULT 3.0
Number of standard deviations from the forecast mean that triggers an anomaly alert.
cost_per_unit NUMBER ≥ 0 · DEFAULT 0.01
Variable cost per unit of traffic served. This value drives the variable portion of cost.
fixed_cost_per_capacity NUMBER ≥ 0 · DEFAULT 0.1
Fixed cost per unit of provisioned capacity. This value drives the fixed portion of cost and all savings figures.
base_scaling_time INTEGER ≥ 1 · DEFAULT 5
Baseline minutes to complete a scale-up. The API multiplies it for larger jumps (see estimated_time_to_scale).
enable_auto_scaling BOOLEAN · DEFAULT false
Whether auto-scaling is already enabled. When false and savings are possible, the response adds an enable_auto_scaling cost recommendation.

Response

RESPONSE 200 OK 
{
  "result": {
    "tenant_context": null,
    "identifier": "api-endpoint-users",
    "current_capacity": 2000,
    "baseline_traffic": 1000,
    "scaling_recommendations": {
      "peak_traffic": 1920.00,
      "average_traffic": 1245.50,
      "current_utilization": 96.0,
      "recommendations": [
        {
          "action": "scale_up",
          "current_capacity": 2000,
          "recommended_capacity": 2304,
          "scaling_factor": 1.15,
          "reason": "Peak traffic (1920) will exceed 80% of current capacity (2000)",
          "urgency": "high",
          "estimated_time_to_scale": 5
        }
      ]
    },
    "capacity_analysis": {
      "current_capacity": 2000,
      "utilization_periods": [
        {"period": 1, "traffic": 1200.00, "utilization": 60.0, "status": "normal"},
        {"period": 2, "traffic": 1920.00, "utilization": 96.0, "status": "critical"}
      ],
      "over_capacity_periods": 0,
      "critical_periods": 4,
      "forecast_duration_minutes": 1440,
      "next_capacity_breach": "2024-06-01",
      "capacity_efficiency": 72.5
    },
    "traffic_alerts": {
      "total_alerts": 1,
      "high_severity": 0,
      "medium_severity": 1,
      "alerts": [
        {
          "type": "traffic_spike",
          "severity": "medium",
          "period": 8,
          "date": "2024-06-01 07:00:00",
          "predicted_traffic": 1920.00,
          "baseline_traffic": 1000,
          "increase_factor": 1.92,
          "message": "Traffic spike predicted: 1920 (1.9x baseline) at Jun 01, 07:00"
        }
      ]
    },
    "cost_optimization": {
      "current_cost": 498.80,
      "optimized_cost": 510.00,
      "potential_savings": -11.20,
      "savings_percentage": -2.2,
      "cost_breakdown": {
        "fixed_cost": 200.00,
        "variable_cost": 298.80
      },
      "recommendations": [
        {
          "type": "enable_auto_scaling",
          "description": "Enable auto-scaling to save approximately $34.50 by dynamically adjusting capacity",
          "potential_savings": 34.50
        }
      ]
    },
    "forecast_data": [
      {"period": 1, "date": "2024-06-01 08:00:00", "forecast": 1200.00, "lower": 1050.00, "upper": 1400.00},
      {"period": 2, "date": "2024-06-01 09:00:00", "forecast": 1920.00, "lower": 1700.00, "upper": 2150.00}
    ]
  },
  "meta": {
    "timing": { "validation": 8.5, "forecasting": 142.3, "total": 150.8 }
  }
}

On success (HTTP 200) the response always has this single shape: a result object with the plan and a meta object with timing. The numeric values above are illustrative. Real figures come from the forecast. Both example arrays are truncated. utilization_periods and forecast_data contain one entry per forecast period.

result Fields

identifier STRING
The series identifier. The response echoes it from the request.
tenant_context STRING | NULL
The tenant tag (null if you do not send one).
current_capacity NUMBER
Current capacity. The response echoes it from traffic_settings.
baseline_traffic NUMBER
Baseline traffic. The response echoes it from traffic_settings.
scaling_recommendations OBJECT
Peak/average traffic, utilization, and the single scaling action (see below).
capacity_analysis OBJECT
Per-period utilization and capacity health metrics (see below).
traffic_alerts OBJECT
Spike and anomaly alerts with severity counts (see below).
cost_optimization OBJECT
Current vs. optimized cost and savings recommendations (see below).
forecast_data ARRAY
The raw traffic forecast that the whole plan uses (see below).

scaling_recommendations Fields

peak_traffic NUMBER
Highest forecast value across all periods.
average_traffic NUMBER
Mean forecast value across all periods.
current_utilization NUMBER
Peak utilization as a percentage: peak_traffic ÷ current_capacity × 100.
recommendations ARRAY
Exactly one recommendation object that describes the scaling action to take (see below).

recommendations[] Fields

action STRING
One of scale_up, scale_down, or maintain (see values below).
current_capacity NUMBER
Your current capacity. The response echoes it.
recommended_capacity NUMBER
Suggested capacity. For scale-up it is ceil(peak × (1 + scaling_buffer)). For maintain it equals current capacity.
scaling_factor NUMBER
recommended_capacity ÷ current_capacity. 1.0 for maintain.
reason STRING
Human-readable rationale for the action.
urgency STRING
How pressing the action is (see values below).
estimated_time_to_scale INTEGER
scale_up only. Estimated minutes to complete the scale-up. The value starts at base_scaling_time. The API doubles it when the scaling factor exceeds 1.5 and triples it above 2.0.
potential_savings NUMBER
scale_down only. The fixed cost that a smaller capacity saves: (current − recommended) × fixed_cost_per_capacity.

action — possible values

Value Returned when Extra field
scale_up Peak utilization > scale_up_threshold. estimated_time_to_scale
scale_down Peak utilization < scale_down_threshold. Recommended capacity never drops below 50% of current. potential_savings
maintain Peak utilization is between the two thresholds. — (none)

urgency — possible values

Value Returned when
critical scale_up and peak utilization > 100% (traffic already exceeds capacity).
high scale_up and utilization > scale_up_threshold × 1.1.
medium scale_up and utilization is just above scale_up_threshold.
low Whenever the action is scale_down.
none Whenever the action is maintain.

capacity_analysis Fields

current_capacity NUMBER
Your current capacity. The response echoes it.
utilization_periods ARRAY
One entry per forecast period: period, traffic, utilization (%), and a status label (see below).
over_capacity_periods INTEGER
Count of periods where utilization exceeds 100%.
critical_periods INTEGER
Count of periods where utilization exceeds 90%.
forecast_duration_minutes INTEGER
Total real-time span of the forecast: periods × period_duration (per the frequency).
next_capacity_breach DATE | NULL
Date of the first period above 80% utilization, or null if none.
capacity_efficiency NUMBER
A 0–100 score. It is highest when average utilization is near the 75% target. Both under-utilization and over-utilization reduce it (each percentage point away from 75% costs 2 points).

utilization_periods[].status — possible values

The API derives each period's status from its utilization (traffic ÷ capacity). It checks the conditions in order and the first match wins.

Value Condition
over_capacity Utilization > 100% — forecast traffic exceeds capacity.
critical Utilization > 90%.
high Utilization > 70%.
normal Utilization > 30%.
low Utilization ≤ 30% — capacity is under-used.

traffic_alerts Fields

total_alerts INTEGER
Total number of alerts across all periods and types.
high_severity INTEGER
Count of alerts with severity: "high".
medium_severity INTEGER
Count of alerts with severity: "medium".
alerts ARRAY
Individual alert objects. Two types can appear — see below. The array is empty when the forecast crosses no threshold.

alerts[] — traffic_spike

The API emits this alert for any period where forecast > baseline_traffic × alert_threshold.

type STRING
Always "traffic_spike".
severity STRING
"high" when traffic > 2× baseline, otherwise "medium".
period INTEGER
1-based index of the forecast period.
date STRING
Datetime of the period (YYYY-MM-DD HH:MM:SS).
predicted_traffic NUMBER
Forecast traffic for that period.
baseline_traffic NUMBER
Baseline for the comparison. The response echoes it from the request.
increase_factor NUMBER
predicted_traffic ÷ baseline_traffic.
message STRING
Human-readable summary of the spike.

alerts[] — anomaly

The API emits this alert for any period whose forecast is more than anomaly_threshold standard deviations from the forecast mean. The anomaly alert shares period, date, predicted_traffic, and message with the spike alert. It differs on these fields:

type STRING
Always "anomaly".
severity STRING
"high" when the z-score > 4, otherwise "medium".
z_score NUMBER
How many standard deviations the period is from the forecast mean (replaces baseline_traffic / increase_factor).

cost_optimization Fields

Costs are relative to your inputs. They are only meaningful if you set realistic cost_per_unit and fixed_cost_per_capacity values. "Optimized" cost sizes capacity to ceil(peak × 1.1) (10% buffer).

current_cost NUMBER
Cost at current capacity: current_capacity × fixed_cost_per_capacity + total_traffic × cost_per_unit.
optimized_cost NUMBER
Cost if capacity equaled ceil(peak × 1.1) (variable cost unchanged).
potential_savings NUMBER
current_cost − optimized_cost. This value can be negative. A negative value means you are currently under-provisioned, and the "optimized" (safe) capacity costs more.
savings_percentage NUMBER
potential_savings ÷ current_cost × 100.
cost_breakdown OBJECT
This object splits the current cost into fixed_cost (capacity) and variable_cost (traffic served).
recommendations ARRAY
Zero or more suggestions (see below). The array is empty when no savings are available.

cost_optimization.recommendations[] — possible entries

type Included when Fields
capacity_optimization potential_savings > 0 (you can safely shrink). description, current_capacity, recommended_capacity, potential_savings
enable_auto_scaling enable_auto_scaling is false and estimated auto-scaling savings > 0. description, potential_savings

forecast_data[] Fields

The raw traffic forecast that every section above uses. It contains one entry per forecast period.

period INTEGER
1-based index of the forecast period.
date STRING
Period date (YYYY-MM-DD, or YYYY-MM-DD HH:00:00 for hourly data).
forecast NUMBER
Point traffic forecast for the period. This is the value that drives scaling, capacity, alerts, and cost.
lower NUMBER
Lower bound of the confidence interval (per confidence_level).
upper NUMBER
Upper bound of the confidence interval — useful for worst-case capacity planning.

meta.timing

Server-side timing in milliseconds: validation (request checks), forecasting (forecast + all infrastructure analysis), and total (whole request).

Reading the Plan

The four sections answer different questions. Use them together rather than in isolation:

Section Answers
scaling_recommendations Should I resize, and to what? Start here — action and urgency tell you whether to act now.
capacity_analysis When does capacity become tight? Watch next_capacity_breach and per-period status to time the change.
traffic_alerts Where are the spikes and anomalies? Send these to on-call alerting. high_severity is a good paging trigger.
cost_optimization What does it cost, and can I save? A negative potential_savings is a signal to scale up, not down.
Usage & Cost
Each call counts as one standard API call. An advanced model consumes 25% more usage, exactly as on the forecast endpoint. The same rate limits apply.

Error Responses

HTTP Status Codes

401
Unauthorized — Invalid or missing API key.
422
Unprocessable Entity — Validation failed — e.g. missing traffic_settings.current_capacity or baseline_traffic, a threshold outside its allowed range, a bad date format, or too many data points for your plan. The body lists per-field errors.
429
Too Many Requests — Rate limit exceeded.
500
Internal Server Error — The forecast or analysis step failed (e.g. the API could not produce a usable forecast). The API returns a generic error body.

422 Validation Error

{
  "message": "The traffic_settings.current_capacity field is required.",
  "errors": {
    "traffic_settings.current_capacity": [
      "The traffic_settings.current_capacity field is required."
    ]
  }
}

500 Forecasting Error

{
  "error": "Traffic forecasting failed",
  "time_taken_ms": 42.7
}

Next Steps

API Reference →
Full endpoint reference, model options, and shared parameters like selection_metric.
Code Examples →
Ready-to-run traffic-forecasting requests in cURL, PHP, Python, and JavaScript.
LAST UPDATED — 30 AUG 2026 · FORECASTAPI DOCS
WAS THIS USEFUL? YES NO