create_forecast
Bind a forecast to a metric in your workspace. Stores the configuration, sets up the schedule, and resolves the source binding immediately so a bad source_id or metric_path errors out before any credits are spent. Run the forecast with run_forecast.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>",
"source_type": "<source_type>",
"source_id": "<source_id>",
"metric_path": "<metric_path>"
},
"name": "create_forecast"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| source_id | Yes | UUID of the report, dashboard, goal, or data source. | |
| transform | No | Series transform applied before fitting. Log helps revenue/traffic series with growing variance. Auto detects when log is beneficial; none forces raw scale. | auto |
| aggregation | No | How multiple raw points falling into the same bucket are combined. Auto picks sum for additive metrics, mean otherwise. Use Mean for rates (CTR, conversion, latency). | auto |
| description | No | ||
| granularity | No | Bucket size for the time series. Hourly requires an hourly data source; the engine refuses to fabricate hourly buckets from daily data. | daily |
| metric_path | Yes | Dot-path to the numeric column. For data_source: the metric key (e.g. "revenue"). For goal: "value" or "percentage". For report: the path inside the insights JSON. For dashboard: "widget_id:metric_name". | |
| source_type | Yes | Which clariBI artifact the metric lives on. Most callers should start with data_source for raw connector metrics or goal to forecast a tracked KPI. | |
| horizon_days | No | How many BUCKETS ahead to project. The per-granularity cap applies: hourly 168, daily 90, weekly 52, monthly 24, quarterly 8, annual 5. The field name is "_days" for backwards compatibility — it counts buckets of the chosen granularity. | |
| non_negative | No | When true, point + lower band clamped at zero. Omit to let the engine heuristic decide (via non_negative_auto=true). | |
| method_override | No | Force a specific forecasting method instead of auto-selecting via walk-forward CV. Valid names: naive, seasonal_naive, moving_average, drift, linear_trend, ar_p, holt_winters, holt_winters_multiplicative, holt_winters_damped, theta, gradient_boost, ensemble_top3. Empty = auto. | |
| include_anomalies | No | ||
| narration_enabled | No | When true, every completed run gets an AI-generated narrative attached (summary, highlights, risks, recommendations, methodology). Costs 1-2 extra AI credits per run. | |
| non_negative_auto | No | When true (default), the backend heuristic owns non_negative and re-evaluates per run based on the metric path. Set false alongside non_negative to lock the choice. | |
| schedule_frequency | No | How often the forecast re-runs. Manual schedules only run when called explicitly via run_forecast. | monthly |
| include_changepoints | No | ||
| include_correlations | No | ||
| schedule_day_of_week | No | ||
| schedule_day_of_month | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| web_url | Yes | ||
| granularity | No | ||
| next_run_at | No | ||
| horizon_days | Yes | ||
| metric_label | No | ||
| schedule_frequency | No |