Concepts
What a goal is, how discovery runs work, and how champions, the graph, and cost fit together.
What is a goal?
A goal pairs a target with an intent:
| Field | What it is |
|---|---|
target_key | The signal to forecast — any key you've pushed to Signals |
goal_type | What kind of answer you want |
Four goal types are supported for a single target:
goal_type | The champion serves |
|---|---|
forecast_value | The target's future values (a point path) |
forecast_distribution | Future values with quantile bands (uncertainty) |
trend | The likelihood of an upward trend, as a probability |
anomaly | The likelihood of anomalous behavior, as a probability |
The goal type matters downstream: trend and anomaly goals serve a
probability in [0, 1] rather than the target's own scale, which changes
which alert metrics apply and how the forecast
renders.
A goal can also target a whole population of signals instead of one:
pass goal_kind: "fleet" with a target_selector and one of the fleet
goal types — rank_by_risk or rank_by_growth. Instead of a champion
forecast, the fleet serves a ranked leaderboard of its members,
re-scored on a cadence. See Fleet goals.
Auto-everything
Only target_key and goal_type are required. Every setting you omit —
horizon_bins, interval_seconds, max_lag_bins — is marked auto and
resolved from measured data by the profile stage on every run, so a
re-run after new data arrives picks fresh values. An explicit value beats
auto and is honored verbatim.
You can see exactly what auto would resolve to before creating anything with
GET /v1/goals/profile-preview.
Discovery runs & the funnel
Creating a goal queues a discovery run. Each run walks a funnel of
stages — profile the target, build the data grid, generate candidate
features, screen and prune them, characterize the survivors, test predictive
lift, validate for stability, then write the results as relationships.
Every stage records what came in, what survived, and why the rest was
rejected, so the run is fully inspectable via
GET /v1/goals/runs/{run_id}.
Runs are also how a goal stays current: re-run any time (or let the goal's discovery policy do it) and the funnel re-validates old relationships and folds in new ones.
Champions & tournaments
After discovery, candidate models compete in a tournament: every entry in the lineup trains on the same discovered drivers and is scored on the same purged walk-forward folds, in the goal type's own metric. The best scorer becomes the champion — the model that serves the goal's forecast.
The champion is a normal platform artifact: a pipeline, a training, and a deployment you can see in your workspace. You can override the automatic pick and select any scored entry instead.
The relationship graph
Discovery's lasting output is a graph: the target at the center, connected to the signals and event streams that predict it by scored, lagged edges. Each edge carries:
- a lag — how far ahead the source leads the target,
- a strength — correlation and walk-forward lift,
- a confidence — the validation q-value behind it,
- a lifecycle —
validated,weakening,exploratory, and so on, as live monitoring re-checks it against fresh data.
The graph powers everything that explains the forecast: drivers-now, scenarios, and multi-hop paths.
Activity & cost
A goal is charged per action, not per month:
- Discovery runs are charged upfront when queued (
discovery.run), scaled by your workspace's candidate volume. - Tournaments are one bounded charge (
discovery.tournament), scaled by the model selection. - Scenarios and their variants charge per simulation; saved results are free to view.
- Live serving charges per prediction on Shared serving.
Every automated action lands in the goal's
timeline with its
trigger and its charge, and automated spend is capped per goal per month.
Estimate everything before creating with
GET /v1/goals/price;
rates live in Billing.