Traffic Forecasting

The traffic-forecasting endpoint turns a historical traffic series into an infrastructure plan. It forecasts future traffic for a single series, then derives scaling recommendations, per-period capacity analysis, traffic alerts for spikes and anomalies, and a cost-optimization summary — everything you need to decide whether to scale, how much, and when.

Base URL

https://forecastapi.com/v2

Authentication

Bearer YOUR_API_KEY

Generate Traffic Plan

POST /traffic-forecasting

Supply your historical traffic series in data, describe your current infrastructure and thresholds in traffic_settings, and receive a full plan back. The endpoint forecasts traffic automatically — you do not call /forecast separately. The forecast is always run with data_type set to "web_traffic", which selects methods tuned for continuous, non-intermittent series.

Request Body

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

Parameter Type Required Description
identifier string Yes Unique identifier for the series (e.g., an endpoint, service, or app name). Echoed back in the response.
data array Yes 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. Sorted ascending automatically.
periods integer Yes Number of future periods to forecast (min 1). Determines how far ahead scaling, capacity, and alerts look.
frequency string Yes Series granularity: H, D, W, M, MS, ME, Q, or Y. Also sets each period's real-time duration used for breach dates and alert timestamps (e.g. H = 60 min). Traffic forecasting is most often used with H or D.
traffic_settings object Yes Infrastructure position and thresholds. Two fields are required; the rest have defaults. See the table below.
start_date date No Anchor for all returned dates (breach date, alert timestamps). Defaults to the last date in data.
model string No Forecasting model behind the plan: standard (default), advanced-quantized, or advanced-patched. See Model Options. Advanced variants cost 25% more usage.
confidence_level float No Confidence level for the forecast intervals returned in forecast_data (0.10–0.99). Default: 0.95.
selection_metric string No Back-testing metric used to pick the winning model: auto (default), combined, mase, or smape. Same semantics as on /forecast.
data_type string No Always overridden to "web_traffic" for this endpoint — any value you send is ignored.
tenant_context string No Optional multi-tenant scoping tag, used for stored-forecast attribution.

traffic_settings Object

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

Field Type Default Description
current_capacity number ≥ 1 required The capacity you can serve today. Drives utilization, scaling decisions, and cost.
baseline_traffic number ≥ 0 required Your normal traffic level. The reference point for spike alerts (see alert_threshold).
scaling_buffer number 0–1 0.2 Headroom kept above peak when sizing recommended capacity. 0.2 = size to 120% of forecast peak.
scale_up_threshold number 0–1 0.8 Utilization fraction (peak ÷ capacity) above which a scale_up is recommended.
scale_down_threshold number 0–1 0.3 Utilization fraction below which a scale_down is recommended. Between the two thresholds, the action is maintain.
alert_threshold number ≥ 1 1.5 Multiple of baseline_traffic that triggers a traffic_spike alert. 1.5 = alert at 150% of baseline.
anomaly_threshold number ≥ 1 3.0 Number of standard deviations from the forecast mean that triggers an anomaly alert.
cost_per_unit number ≥ 0 0.01 Variable cost per unit of traffic served. Drives the variable portion of cost.
fixed_cost_per_capacity number ≥ 0 0.1 Fixed cost per unit of provisioned capacity. Drives the fixed portion of cost and all savings figures.
base_scaling_time integer ≥ 1 5 Baseline minutes to complete a scale-up. Multiplied for larger jumps (see estimated_time_to_scale).
enable_auto_scaling boolean false Whether auto-scaling is already enabled. When false and savings are possible, the response adds an enable_auto_scaling cost recommendation.

Response

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

The response always has this single shape on success (HTTP 200): 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

Field Type Description
identifier string The series identifier, echoed from the request.
tenant_context string | null The tenant tag (null if not sent).
current_capacity number Current capacity, echoed from traffic_settings.
baseline_traffic number Baseline traffic, echoed 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 the whole plan is built on (see below).

scaling_recommendations Fields

Field Type Description
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 describing the scaling action to take (see below).

recommendations[] Fields

Field Type Description
action string One of scale_up, scale_down, or maintain (see values below).
current_capacity number Your current capacity, echoed for convenience.
recommended_capacity number Suggested capacity. For scale-up, ceil(peak × (1 + scaling_buffer)); equals current capacity for maintain.
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: base_scaling_time, doubled when scaling factor > 1.5, tripled when > 2.0.
potential_savings number scale_down only. Fixed-cost saved by shrinking: (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 Always returned for scale_down.
none Always returned for maintain.

capacity_analysis Fields

Field Type Description
current_capacity number Your current capacity, echoed.
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 covered by the forecast: periods × period_duration (per the frequency).
next_capacity_breach date | null Date of the first period exceeding 80% utilization, or null if none.
capacity_efficiency number A 0–100 score, highest when average utilization sits near the 75% sweet spot. Both under- and over-utilization reduce it (each percentage point away from 75% costs 2 points).

utilization_periods[].status — possible values

Each period's status is derived from its utilization (traffic ÷ capacity). Checked in order — 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

Field Type Description
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. Empty when no thresholds are crossed.

alerts[] — traffic_spike

Emitted for any period where forecast > baseline_traffic × alert_threshold.

Field Type Description
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 used for comparison, echoed from the request.
increase_factor number predicted_traffic ÷ baseline_traffic.
message string Human-readable summary of the spike.

alerts[] — anomaly

Emitted for any period whose forecast is more than anomaly_threshold standard deviations from the forecast mean. Shares period, date, predicted_traffic, and message with the spike alert, and differs on these fields:

Field Type Description
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).

Field Type Description
current_cost number Cost at current capacity: current_capacity × fixed_cost_per_capacity + total_traffic × cost_per_unit.
optimized_cost number Cost if capacity were sized to ceil(peak × 1.1) (variable cost unchanged).
potential_savings number current_cost − optimized_cost. 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 Current cost split into fixed_cost (capacity) and variable_cost (traffic served).
recommendations array Zero or more suggestions (see below). 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 is derived from — one entry per forecast period.

Field Type Description
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 it get tight? Watch next_capacity_breach and per-period status to time the change.
traffic_alerts Where are the spikes/anomalies? Feed these into on-call alerting; high_severity is a good paging trigger.
cost_optimization What's it costing, 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. Using 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. no usable forecast could be produced). 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.