Run a forecast

Get predictions out of a deployed model — by goal, pipeline, or pinned deployment.

The fastest path: point segment inference at a goal. The platform prepares model input from live data, and the URL keeps working through champion swaps and promotions.

curl -X POST "$API_BASE/v1/inference/goals/$GOAL_ID/infer-segment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

from predictai import PredictAI

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

data = client.inference.post_inference_goals_by_goal_id_infer_segment(GOAL_ID, json={})

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

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

const data = await client.inference.postInferenceGoalsByGoalIdInferSegment(GOAL_ID, { json: {} });

{
  "predictions": [
    {
      "label": "daily_sales",
      "point": [1250.75, 1274.1, 1268.3, …]
    }
  ],
  "horizon": 14,
  "labels": ["daily_sales"],
  "forecast_horizon": 14,
  "model_id": "9f2c41d8-…",
  "deployment_id": "c4a7…",
  "deployment_type": "shared",
  "segment_id": "SEGMENT_ID",
  "segment_name": "Retail daily",
  "training_id": "7d81c3f0-…",
  "sequence_length": 15,
  "feature_names": ["website_visitors", "marketing_spend", …],
  "inference_id": "b7e6…",
  "latency_ms": 245.67,
  "timestamp": "2026-07-15T12:04:45.123000+00:00Z",
  "data_period": {
    "start": "2026-06-30T00:00:00Z",
    "end": "2026-07-14T00:00:00Z"
  }
}

The body is optional — an empty {} is a complete request, because the platform derives everything from the deployment behind the goal. The body options (quantiles, horizon overrides for foundation deployments, feature debug) work here too.

Response fields

Responses are top-level payloads — there is no {"data": …} wrapper on inference routes.

Field	Meaning
`predictions`	Always an array of `{ label, point }` entries — one per output label, `point` spanning the horizon — with optional `quantiles` for probabilistic forecasts.
`horizon` / `labels`	How many steps were predicted, for which segment labels.
`deployment_id` / `deployment_type`	Which concrete deployment actually served the request.
`model_id` / `training_id`	The pipeline and the training behind the serving model.
`sequence_length` / `feature_names`	The input shape: timesteps of history and the features prepared, in input order.
`data_period`	The window of live data the input was built from.
`inference_id`	The request's ID — appears in history and realtime events.
`latency_ms`	End-to-end serving latency.

Pipeline alias

Same request against the pipeline you own — resolves to its current champion's deployment, survives promotions:

curl -X POST "$API_BASE/v1/inference/pipelines/$PIPELINE_ID/infer-segment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{}'

from predictai import PredictAI

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

data = client.inference.post_inference_pipelines_by_pipeline_id_infer_segment(PIPELINE_ID, json={})

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

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

const data = await client.inference.postInferencePipelinesByPipelineIdInferSegment(PIPELINE_ID, { json: {} });

Version-pinned deployment, raw tensor

To pin an exact version — or to send your own model input — call the deployment directly with raw /infer:

Field	Meaning
`input` required	A flat vector or a batch of vectors, in the exact feature order the model was trained on.
`parameters` optional	Serving parameters passed through to the model server.

curl -X POST "$API_BASE/v1/inference/deployments/$DEPLOYMENT_ID/infer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [[0.42, 0.13, 0.77, 0.91, 0.05, …]],
    "parameters": {}
  }'

from predictai import PredictAI

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

data = client.inference.post_inference_deployments_by_deployment_id_infer(DEPLOYMENT_ID, json={
    "input": [[0.42, 0.13, 0.77, 0.91, 0.05, …]],
    "parameters": {},
})

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

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

const data = await client.inference.postInferenceDeploymentsByDeploymentIdInfer(DEPLOYMENT_ID, {
  json: {
    input: [[0.42, 0.13, 0.77, 0.91, 0.05, …]],
    parameters: {},
  },
});

{
  "predictions": [
    { "label": "output", "point": [0.8734, 0.8812, …] }
  ],
  "horizon": 14,
  "labels": ["output"],
  "model_id": "9f2c41d8-…",
  "training_id": "7d81c3f0-…",
  "deployment_id": "c4a7…",
  "deployment_type": "shared",
  "inference_id": "b7e6…",
  "latency_ms": 189.42,
  "timestamp": "2026-07-15T12:04:45.123000+00:00Z",
  "usage": {
    "input_tokens": 142,
    "output_tokens": 96
  }
}

Raw inference has no segment labels to map to, so predictions come back under the synthetic output label — map them by index. Values are the model's direct output; segment inference is what applies inverse scaling and label mapping for you. Raw /infer is also available on the pipeline and goal aliases.

If you get a 202

Segment inference on a foundation deployment returns 202 Accepted when the model server was cold:

{
  "async": true,
  "status": "pending",
  "inference_id": "b7e6…",
  "deployment_id": "c4a7…",
  "segment_id": "SEGMENT_ID",
  "message": "Inference started. The model server may be cold; this can take a few minutes."
}

Subscribe to the workspace's realtime channel for the inference.completed event, or poll GET /v1/inference/{inference_id} until the record appears. See Concepts.

What it costs

Inference on Shared serving is metered in credits per request (rate depends on the model kind); Dedicated serving includes inference in its flat daily hosting fee. A request that fails to produce a forecast is refunded automatically. Rates live in Billing.

Errors

All inference errors use the coded envelope:

{
  "error": {
    "code": "DEPLOYMENT_NOT_FOUND",
    "message": "Deployment c4a7… not found or not ready",
    "details": { … }
  }
}

Status	Code	Why
`400`	`INVALID_FORMAT`	Raw infer: body isn't JSON
`400`	`MISSING_INPUT`	Raw infer: no `input` field
`400`	`VALIDATION_ERROR`	Segment infer on a foundation deployment without `segment_id`
`400`	`CONFIGURATION_ERROR`	The deployment's model/segment configuration can't be resolved
`401`	`UNAUTHORIZED`	Token missing or invalid
`403`	`FORBIDDEN`	You don't have access to this deployment
`404`	`DEPLOYMENT_NOT_FOUND`	Deployment doesn't exist or isn't ready
`404`	`MODEL_NOT_DEPLOYED`	Pipeline/goal alias has no active deployment — deploy a trained model first
`4xx`/`5xx`	`INFERENCE_FAILED`	The serving path failed; status mirrors the upstream failure
`500`	`DATA_PREPARATION_ERROR`, `INPUT_PREPARATION_ERROR`	Segment infer: live data couldn't be fetched or shaped
`500`	`INTERNAL_ERROR`	Unexpected server error

INFERENCE_FAILED errors carry a retryable flag — true means the failure looks transient (for example, the model server was cold or restarting) and an immediate retry is likely to succeed.