Skip to Content
API ReferencePredictive Models

Predictive Models API

Create, train, promote and score predictive models, manage the feature library they train on, and run RFM segmentation and Feature Analysis. Every path is under /api/v1/workspaces/{id} unless shown otherwise, and every call needs the headers described in Authentication.

Errors return {"error": "<message>"} with a 4xx or 5xx status. A missing permission is 403 with permission denied: <permission>.

These endpoints, and the source’s /ml-readiness check, are available only in a workspace with Machine Learning enabled. Your organization admin turns it on per workspace. In a workspace without it, every one of them answers 404.

Permissions

PermissionGrants
predictive_traits.readRead models, versions, runs, scores and retention proposals
predictive_traits.writeCreate, change, pause, resume and delete models; import BYO scores
predictive_traits.trainTrain, rescore, and approve or reject a training run waiting for approval
predictive_traits.promotePromote a version, approve a dominant feature, decide retention proposals
features.read / features.writeRead / change the feature library
rfm_segmentation.read / .write / .trainRead / change / run RFM segmentations
models.read / models.writeRead / run Feature Analysis

Owners and admins hold all of them. Members hold predictive_traits.read, features.read, features.write and rfm_segmentation.read.


Predictive Models

MethodPathPermissionDescription
GET/predictive-modelsreadList models
POST/predictive-modelswriteCreate a trained model
POST/predictive-models/ingest-byowriteRegister a BYO scored table
GET/predictive-models/{predictiveId}readGet a model
PUT/predictive-models/{predictiveId}writeChange a trained model’s configuration and schedules
DELETE/predictive-models/{predictiveId}writeDelete a model
POST/predictive-models/{predictiveId}/pausewritePause scheduled training and scoring
POST/predictive-models/{predictiveId}/resumewriteResume them
POST/predictive-models/{predictiveId}/retry-byo-viewwriteRecreate a BYO model’s view after an error

Create a Trained Model

POST /api/v1/workspaces/{id}/predictive-models

{ "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "name": "Churn risk 30d", "description": "Customers likely to go quiet in the next 30 days", "problem_type": "classification", "result_type": "probability", "algorithm_hint": "auto", "retrain_cron": "0 3 1 * *", "rescore_cron": "0 4 * * *", "retained_versions": 5, "training_config": { "prediction_window_days": 30, "holdout_percent": 10, "holdout_strategy": "random", "feature_ids": ["a1e8400-e29b-41d4-a716-446655440000"], "outcome_event": { "kind": "event_based", "source_model_id": "880e8400-e29b-41d4-a716-446655440000", "timestamp_column": "event_time", "aggregate_function": "absence" }, "cost_budget_usd": 25 } }
FieldRequiredNotes
parent_model_idYesA parent model in this workspace
nameYesUnique in the workspace; the slug is derived from it (409 on a duplicate)
problem_typeYesclassification or regression
result_typeYesprobability or percentile for classification; number for regression
algorithm_hintNoauto (default), boosted_tree, logistic, linear, or automl (BigQuery only, and only when AutoML is enabled for the workspace)
retrain_cron, rescore_cronNoCron expressions in UTC; omit for manual only
retained_versionsNoDefault 5
training_config.prediction_window_daysYesHow far ahead the outcome is observed
training_config.feature_ids / declared_columnsYes, at least oneActive features of the same parent model, or parent columns
training_config.outcome_eventYeskind: "event_based" with source_model_id, timestamp_column and an optional aggregate_function (absence, sum, avg, min, max; regression needs one, absence is classification only), or kind: "sql" with custom_label_sql
training_config.holdout_percentNo0–99
training_config.holdout_strategyNorandom or temporal
training_config.training_as_ofNoA past date (YYYY-MM-DD or RFC 3339)
training_config.eligibility_filterNoA filter restricting who is trained and scored
training_config.cost_budget_usdNoTraining estimated above it waits for approval; 0 disables the check
training_config.hyperparamsNoValidated against the model configuration schema
training_config.leakage_dominance_threshold, leakage_cumulative_top3_thresholdNo0–1

Returns 201 with the model. Nothing is trained until you call Train or the retrain schedule fires.

Register BYO Scores

POST /api/v1/workspaces/{id}/predictive-models/ingest-byo

{ "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "name": "Vendor LTV", "result_type": "number", "byo_config": { "source_model_id": "990e8400-e29b-41d4-a716-446655440000", "entity_id_column": "customer_id", "score_column": "predicted_ltv", "percentile_column": "ltv_percentile", "scored_at_column": "scored_at" } }

source_model_id, entity_id_column and score_column are required, and the score column must be numeric. Without percentile_column the percentile is computed when the view is read. Returns 201. If the view cannot be created the model is still returned, with status: "error" and the reason in status_error; fix the table and call retry-byo-view rather than registering it again.

Update a Model

PUT /api/v1/workspaces/{id}/predictive-models/{predictiveId}

Accepts algorithm_hint, training_config, retrain_cron, rescore_cron and retained_versions. training_config and both schedules are replaced as sent; an empty cron makes that schedule manual only. Trained models only.

Delete a Model

DELETE /api/v1/workspaces/{id}/predictive-models/{predictiveId} returns 204. A model that an audience, canvas, journey, destination rule, deletion rule, subset or audience template filters on is refused with 409, naming what uses it.

The Model Object

{ "id": "550e8400-e29b-41d4-a716-446655440000", "workspace_id": "660e8400-e29b-41d4-a716-446655440000", "name": "Churn risk 30d", "slug": "churn_risk_30d", "source": "trained", "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "problem_type": "classification", "result_type": "probability", "algorithm_hint": "auto", "training_config": { "prediction_window_days": 30, "...": "..." }, "current_version_id": "bb0e8400-e29b-41d4-a716-446655440000", "serving_view_ref": "`my-project`.`cdp_planner`.`current_predictions_churn_risk_30d`", "retrain_cron": "0 3 1 * *", "rescore_cron": "0 4 * * *", "retained_versions": 5, "status": "ready", "status_error": "", "created_by": "aae8400-e29b-41d4-a716-446655440000", "created_at": "2026-10-01T09:30:00Z", "updated_at": "2026-10-02T04:05:00Z" }

status is one of draft, training, ready, paused, error or degraded. source is trained or byo; a BYO model carries byo_config instead of training_config.


Training, Versions and Scoring

MethodPathPermissionDescription
POST/predictive-models/{predictiveId}/traintrainStart a training run
GET/predictive-models/{predictiveId}/training-runsreadThe latest 50 training runs
POST/predictive-models/{predictiveId}/training-runs/{runId}/approvetrainRun a training run that is waiting for approval
POST/predictive-models/{predictiveId}/training-runs/{runId}/rejecttrainCancel it
GET/predictive-models/{predictiveId}/versionsreadList versions with metrics and feature importance
POST/predictive-models/{predictiveId}/versions/{versionId}/promotepromoteMake a version current and queue a rescore
POST/predictive-models/{predictiveId}/versions/{versionId}/approve-featurepromoteAccept a dominant feature as legitimate
POST/predictive-models/{predictiveId}/rescoretrainStart a scoring run with the current version
GET/predictive-models/{predictiveId}/scoring-runsreadThe latest 50 scoring runs
GET/predictive-models/{predictiveId}/scoresreadA sample of current scores
GET/predictive-runsreadRecent training and scoring runs across the workspace

Train

POST /api/v1/workspaces/{id}/predictive-models/{predictiveId}/train returns 202 with the training run. When the model has a cost budget and the estimate is above it, or cannot be made, the run is created with status awaiting_approval; approve it with …/training-runs/{runId}/approve. Add ?force=true to skip the budget check. A run already in progress is 409.

Training run status: pending, awaiting_approval, compiling, training, evaluating, completed, failed, cancelled. Each run carries its estimated cost range, its measured cost when known (cost_status: pending, provisional, final, unattributed, unavailable, not_applicable), and the version it produced.

Versions

Version status: pending_review, promoted, retired, archived, failed. Each version carries metrics (for example auc, precision, recall for classification, rmse for regression), feature_importance (feature, importance, method, direction), row counts, and promotion_source (auto, manual or rollback). A suspected-leakage flag is in metrics.

approve-feature takes {"feature_name": "days_since_signup"} and returns {"status": "approved"}. Later versions are flagged again only if that feature’s share of importance moves.

Rescore

POST …/rescore returns 202 with the scoring run. Scoring run status: pending, running, completed, failed, cancelled. A completed run carries rows_scored, view_swapped_at, a score summary, and its drift (psi_vs_reference, psi_vs_previous).

Sample Scores

GET …/scores?mode=top&limit=20

mode is top (default), bottom or random; limit defaults to 20, up to 500.

{ "rows": [ { "entity_id": "c_0042", "score": 0.93, "percentile": 100, "scored_at": "2026-10-02T04:03:11Z" } ] }

Model Configuration Schema

GET /api/v1/predictive/model-config-schema (not workspace-scoped) returns the hyperparameters a model may set with their bounds and defaults, the class-imbalance and random-seed options, and the default leakage thresholds. It supports If-None-Match.


Feature Library

MethodPathPermissionDescription
GET/features?parent_model_id=features.readList features, optionally for one parent model
POST/featuresfeatures.writeCreate a feature
GET/features/{featureId}features.readGet a feature
PUT/features/{featureId}features.writeUpdate a feature
DELETE/features/{featureId}features.writeDelete a feature (409 while a model uses it)
GET/features/recipe-readinessmodels.readWhether starter recipes can bind here: the readiness checklist and the parent/related model candidates
{ "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "name": "Orders last 30 days", "feature_kind": "aggregation", "result_type": "number", "config": { "source_model_id": "880e8400-e29b-41d4-a716-446655440000", "function": "count", "timestamp_column": "ordered_at", "window_days": 30 } }

feature_kind is column (with config.column_name) or aggregation (with source_model_id, function, timestamp_column, and value_column unless the function is count or recency_days). Functions: count, count_distinct, sum, avg, min, max, recency_days. result_type is number, text, boolean or timestamp.


RFM Segmentation

MethodPathPermissionDescription
GET/rfm-segmentationsreadList segmentations
POST/rfm-segmentationswriteCreate one (in draft)
POST/rfm-segmentations/suggest-monetary-columnswriteSuggest the monetary columns of an event model
POST/rfm-segmentations/preflightwriteCheck the data a segmentation would read, without saving
GET/rfm-segmentations/{configId}readGet one
PUT/rfm-segmentations/{configId}writeUpdate it, including status (draft, active, paused)
DELETE/rfm-segmentations/{configId}writeDelete it; its published model is kept
POST/rfm-segmentations/{configId}/runtrainRun it now
GET/rfm-segmentations/{configId}/runsreadThe latest 50 runs
POST/rfm-segmentations/{configId}/publishwriteRetry registering the output model
{ "parent_model_id": "770e8400-e29b-41d4-a716-446655440000", "name": "Customer RFM", "event_source_model_id": "880e8400-e29b-41d4-a716-446655440000", "event_entity_id_column": "customer_id", "event_timestamp_column": "ordered_at", "event_condition_sql": "status = 'completed'", "monetary_columns": ["order_total"], "window_days": 365, "num_clusters": 10, "min_population": 500, "schedule_cron": "0 5 * * 1" }

event_entity_id_column is the event model’s column that identifies the parent record. It must be the event-side key of a relationship from the parent to the event model (one-to-one or one-to-many, single column); any other column is refused with 400, naming the right one. It may be omitted on create and on preflight: it is then taken from the one such relationship and stored, and refused with 400 when there are several (name one), when the only links can’t be used, or when there is no relationship (then it is required). Update requires it. Preflight takes parent_model_id too, and reports a link problem as a failing link check. window_days is 1–365, num_clusters 2–10, and min_population defaults to 500. Send event_filter (a filter tree) instead of event_condition_sql to build the condition visually. A completed run’s cluster_summary lists each segment’s segment_name, value_tier (low_value, mid_value, high_value), averages, size and share. Supported on BigQuery, Databricks and Snowflake.


Feature Analysis

MethodPathPermissionDescription
POST/feature-analysis/runmodels.writeProfile a model: {"model_id": "…"}
GET/feature-analysis?model_id=&run_id=models.readThe stored result, latest or a named run; never scans
GET/feature-analysis/runs?model_id=models.readPast runs

Each column in the result has a state (computed, not_computed, unavailable), its fill rate and distinct count, and, for columns with at most 100 distinct values, top_values with row and customer counts. A run profiles up to 200 columns. Refusals return 400 with a code, such as feature_analysis_unsupported.


Retention Proposals

Where version retention is enabled, versions past a model’s retained_versions are proposed for removal before anything is dropped.

MethodPathPermissionDescription
GET/predictive-retention/batchesreadPending proposals, grouped by version, with the warehouse objects and their sizes
POST/predictive-retention/batches/{versionId}/approvepromoteApprove removing that version’s objects
POST/predictive-retention/batches/{versionId}/rejectpromoteKeep them
POST/predictive-retention/registry-orphans/{batchId}/approvepromoteApprove removing an orphaned registry entry
POST/predictive-retention/registry-orphans/{batchId}/rejectpromoteKeep it

Example

curl -X POST https://agentic.zeotap.com/api/v1/workspaces/{id}/predictive-models/{predictiveId}/train \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"
Last updated on