Goals & discovery runs

Goals

Everything else in predictAI is a tool you operate. A goal flips the model: you declare what you want forecast, and the platform operates the tools.

curl -X POST "$API_BASE/v1/goals" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{ "target_key": "daily_sales", "goal_type": "forecast_value" }'

from predictai import PredictAI

client = PredictAI(token="pa_live_…", workspace_id="ws_…")

data = client.goals.post_goals(json={
    "target_key": "daily_sales",
    "goal_type": "forecast_value",
})

import { PredictAI } from "@predictai/sdk";

const client = new PredictAI({ token: "pa_live_…", workspaceId: "ws_…" });

const data = await client.goals.postGoals({
  json: {
    target_key: "daily_sales",
    goal_type: "forecast_value",
  },
});

Only two fields are required — the target signal and the goal type (forecast_value, forecast_distribution, trend, or anomaly). Every setting you omit (horizon, resolution, lags) is resolved automatically from your data and re-tuned on every run.

What a discovery run does

Creating a goal queues a discovery run. Each run walks a funnel:

1. Profile — measure the target: seasonality, cadence, gaps.
2. Discover — scan the workspace for signals that drive the target, building a relationship graph of scored, lagged edges.
3. Tournament — train candidate models on the discovered drivers and score them against each other.
4. Champion — deploy the winner and produce the goal's forecast.

The goal then stays live: alerts watch the forecast, retraining keeps the champion fresh, and you can re-run discovery any time the world changes.

What hangs off a goal

Everything goal-related is a facet of the same object, under /v1/goals:

• the relationship graph — what drives your target, with lags and strengths,
• the tournament — the model lineup and scores, with manual override,
• the forecast — current values, timeline, and drivers-now view,
• scenarios — what-if simulations over the discovered graph,
• the analyst — a conversational interface over all of the above,
• alerts — conditions on the forecast that fire in realtime.

Goals vs pipelines

Use pipelines when you know exactly what you want to train and on what. Use goals when you'd rather declare the outcome and let the platform find the how. They coexist happily — a goal's champion is a pipeline under the hood, visible in your workspace like any other.