Forecast a Metric in clariBI

Forecasting in clariBI projects any metric in your workspace into the next 1 to 90 days, finds the other series that move with it, and tells you which findings are stable enough to act on. This article walks through binding a forecast to a report, dashboard widget, goal, or data source column, picking a schedule, and reading the result.

What you need

• A Starter, Professional, or Enterprise plan (Forecasting is gated by the predictive_analysis feature 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.

Create a forecast

1. Open Forecasting in the left sidebar and click New Forecast.
2. 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 value or percentage field across its progress history.
3. Choose granularity (daily, weekly, or monthly) and horizon (1 to 90 days).
4. Decide which checks to include: correlated drivers, anomalies, structural changes.
5. 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.

How the engine picks a method

Each run does a walk forward backtest across nine forecasting methods: Naive, Seasonal Naive, Moving Average, Drift, Linear Trend, AR(p), Holt Winters, Theta, and Gradient Boosting on lag features. 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, trend strength, seasonality, variability) so subsequent runs on similar series skip the backtest.

How drivers are surfaced

Once the target forecast is built, clariBI scores every other numeric series in the workspace for Pearson correlation, Spearman rank correlation, and cross lag windows up to 14 days. Benjamini Hochberg correction at q=0.05 keeps the false discovery rate in check across the candidate pool. A 200 iteration 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.

Anomalies and structural changes

The historical series is also checked for outliers (combined z score and IQR fence) and structural breaks (segmented OLS with a Chow style F test). Each anomaly carries a severity label (mild, moderate, severe). Each changepoint reports the slope before and after the break so you can recognise the date the regime flipped.

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 > 180)               # long history
     + (1 if granularity == 'weekly'           # weekly long history
        and history_days > 365)

floor = 1, cap = 10

Reading the result

The forecast detail page shows the historical line, the projection with its prediction band, and a table of correlated metrics with the lag and stability columns. Click any driver row to see its own projection. Anomalies and changepoints appear below the chart, each annotated with the exact date.

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, create_forecast, run_forecast). 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.