Forecasting in clariBI projects any metric in your workspace into the future, finds the other series that move with it, and tells you which findings are stable enough to act on. v2 adds six granularities (from hourly to annual), calibrated 50/80/95 percent prediction intervals, an AI narrative on every run, log/non-negative transforms, and a Trust tab that scores past forecasts against the actuals that have since materialised. This article walks through binding a forecast, picking a schedule, and reading the result.
What you need
- A Starter, Professional, or Enterprise plan (Forecasting is gated by the
predictive_analysisfeature flag). - At least one connected data source, generated report, or active goal with a numeric metric.
- AI credits, since each run costs between 1 and 10 credits depending on complexity, plus 1 to 2 extra for the AI narrative (skip via the narration toggle).
Create a forecast
- Open Forecasting in the left sidebar and click New Forecast.
- Pick the metric source. The picker groups options by surface:
- Data source aggregation uses the time series clariBI preprocessed when the source was connected. Best for raw connector data (Stripe MRR, Google Ads spend, GA4 sessions).
- Report metric binds to a value inside a generated report's insights JSON. Picks up new datapoints every time the report regenerates.
- Dashboard widget metric reads from the data source the widget is bound to.
- Goal progress forecasts your goal's
valueorpercentagefield across its progress history.
- Choose granularity — hourly (max horizon 168), daily (90), weekly (52), monthly (24), quarterly (8), or annual (5). The horizon input clamps to the per-granularity cap automatically.
- Decide which checks to include: correlated drivers, anomalies, structural changes, AI narrative.
- Set the schedule. Default is monthly at 2 AM UTC. Switch to daily or weekly for fast moving series, or set the cadence to manual for on demand only.
- Optional — open the Advanced section to override the engine defaults:
- Aggregator (auto/sum/mean/last/max) controls how multiple raw points in the same bucket combine. Auto picks sum for additive metrics (revenue, clicks) and mean for rates (CTR, conversion, latency).
- Transform (auto/none/log) applies a log compression before fitting on positive-only series with growing variance.
- Method override pins a specific forecasting method instead of letting walk-forward CV pick.
- Non-negative clamp (auto/true/false) clips the point + lower band at zero. Auto enables this for count-like metric paths.
How the engine picks a method
Each run does a walk-forward backtest across twelve forecasting methods: Naive, Seasonal Naive, Moving Average, Drift, Linear Trend, AR(p) with AIC order selection, Holt-Winters (additive, multiplicative, damped variants), STL-Theta, Gradient Boosting on lag + rolling + seasonal phase features, and a top-3 ensemble that averages the three best-performing single methods. The winner is the method with the lowest sMAPE on the rolling holdout. clariBI caches the winner per organisation keyed on a fingerprint of the series (length bucket, trend strength, seasonality, variability, granularity, horizon bucket) so subsequent runs on similar series skip the backtest.
Calibrated prediction intervals
Walk-forward CV keeps the actual-minus-predicted residuals at every horizon step. The engine emits three nested bands — 50, 80, and 95 percent confidence — by taking empirical quantiles of those residuals. Wide bands mean the historical fit was noisy; tight bands mean the method generalised well. When a series exceeds your tolerance for uncertainty, switch to a coarser granularity or a shorter horizon.
How drivers are surfaced
Once the target forecast is built, clariBI scores every other numeric series in the workspace — across data sources, goals, and reports — for Pearson correlation, Spearman rank correlation, and cross lag windows up to 14 buckets. Benjamini-Hochberg correction at q=0.05 keeps the false discovery rate in check across the candidate pool, with per-candidate rank correction so tied p-values get distinct adjusted q-values. A 200-iteration moving-block bootstrap then estimates the stability of each surviving correlation; if its 80 percent confidence interval crosses zero, the driver is labelled fragile so you know to discount it. When the gradient-boost method wins AND a stable leading-indicator exists with a lag inside the horizon, the engine pins it as an exogenous regressor on the headline forecast, closing the loop between correlation discovery and projection.
Anomalies and structural changes
The historical series is checked for outliers using seasonal-aware detection — the seasonal cycle is removed before the linear detrend so legitimate Q4 peaks don't get flagged as anomalies. IQR-fence and z-score detection both run; each anomaly carries a severity label (mild, moderate, severe).
Structural changepoints surface in two flavours: level breaks (segmented OLS with a Chow-style F test, Bonferroni-corrected so long random walks don't accumulate false positives) and variance shifts (heteroskedasticity changes that level breaks miss). Each level changepoint reports the slope before and after the break; each variance changepoint reports the pre and post variance.
AI narrative
Every completed run gets a structured prose narrative attached: a 60-150 word headline summary, 3-5 decision-relevant highlights, 2-4 risks that could invalidate the projection, 2-4 concrete recommendations, and a short methodology note explaining why the chosen method won. The narrative grounds every claim in the structured forecast result so it never invents numbers. Toggle AI narrative off in the modal to skip the LLM step entirely and save 1-2 credits per run. You can regenerate a narrative on demand from the detail view if you tweaked settings or want a fresh take.
Trust tab
The detail view's Trust tab compares each prior run's projection against the actuals that have since materialised. The table shows the run date, winning method, horizon length, observed count (how many forecast points now have a real value to compare against), the realised sMAPE, the run's own backtest sMAPE at creation time, and the difference. Use this to spot when a backtest was systematically optimistic vs. realised performance, or to confirm that your forecasts have been getting more accurate over time.
Credit cost
Per run cost is deterministic. The breakdown shows up in the run detail page:
cost = 1 # base run
+ (2 if target method not cached) # backtest
+ ceil(correlated_count / 4) # discovered drivers
+ (1 if history_days > long_threshold) # per-granularity
+ (1 if history_days > very_long_thresh) # per-granularity
floor = 1, cap = 10Long-history thresholds scale by granularity: hourly 30d/90d, daily 180d/365d, weekly 365d/1095d, monthly 1095d/2920d, quarterly 1825d/5475d, annual 3650d/9125d. AI narrative adds 1-2 credits on top when enabled.
Reading the result
The forecast detail page shows the historical line, the projection with its three nested confidence bands as a fan chart, the AI narrative card, a table of correlated metrics with the lag and stability columns, and the anomalies and changepoints. Click any driver row to see its own projection.
Reach forecasts from outside the app
The same configuration, scheduling, and run history are exposed through the public REST API at /api/v1/forecasts/ (scopes forecasts:read, forecasts:write, forecasts:run) and through the MCP server (list_forecasts, get_forecast, get_forecast_run, get_forecast_trust, create_forecast, run_forecast, regenerate_forecast_narrative). The MCP tools are tier gated the same way as the in-app view.
When a run fails
If a forecast fails (insufficient history, source removed, transient worker error), the credits reserved up front are refunded in full and the run is marked refunded. Three consecutive failures on a scheduled forecast auto pause the schedule so it stops burning credits; resume it from the schedule controls on the forecast detail page.
See the Forecasting product page for a higher level overview.