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
| Permission | Grants |
|---|---|
predictive_traits.read | Read models, versions, runs, scores and retention proposals |
predictive_traits.write | Create, change, pause, resume and delete models; import BYO scores |
predictive_traits.train | Train, rescore, and approve or reject a training run waiting for approval |
predictive_traits.promote | Promote a version, approve a dominant feature, decide retention proposals |
features.read / features.write | Read / change the feature library |
rfm_segmentation.read / .write / .train | Read / change / run RFM segmentations |
models.read / models.write | Read / 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
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /predictive-models | read | List models |
POST | /predictive-models | write | Create a trained model |
POST | /predictive-models/ingest-byo | write | Register a BYO scored table |
GET | /predictive-models/{predictiveId} | read | Get a model |
PUT | /predictive-models/{predictiveId} | write | Change a trained model’s configuration and schedules |
DELETE | /predictive-models/{predictiveId} | write | Delete a model |
POST | /predictive-models/{predictiveId}/pause | write | Pause scheduled training and scoring |
POST | /predictive-models/{predictiveId}/resume | write | Resume them |
POST | /predictive-models/{predictiveId}/retry-byo-view | write | Recreate 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
}
}| Field | Required | Notes |
|---|---|---|
parent_model_id | Yes | A parent model in this workspace |
name | Yes | Unique in the workspace; the slug is derived from it (409 on a duplicate) |
problem_type | Yes | classification or regression |
result_type | Yes | probability or percentile for classification; number for regression |
algorithm_hint | No | auto (default), boosted_tree, logistic, linear, or automl (BigQuery only, and only when AutoML is enabled for the workspace) |
retrain_cron, rescore_cron | No | Cron expressions in UTC; omit for manual only |
retained_versions | No | Default 5 |
training_config.prediction_window_days | Yes | How far ahead the outcome is observed |
training_config.feature_ids / declared_columns | Yes, at least one | Active features of the same parent model, or parent columns |
training_config.outcome_event | Yes | kind: "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_percent | No | 0–99 |
training_config.holdout_strategy | No | random or temporal |
training_config.training_as_of | No | A past date (YYYY-MM-DD or RFC 3339) |
training_config.eligibility_filter | No | A filter restricting who is trained and scored |
training_config.cost_budget_usd | No | Training estimated above it waits for approval; 0 disables the check |
training_config.hyperparams | No | Validated against the model configuration schema |
training_config.leakage_dominance_threshold, leakage_cumulative_top3_threshold | No | 0–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
| Method | Path | Permission | Description |
|---|---|---|---|
POST | /predictive-models/{predictiveId}/train | train | Start a training run |
GET | /predictive-models/{predictiveId}/training-runs | read | The latest 50 training runs |
POST | /predictive-models/{predictiveId}/training-runs/{runId}/approve | train | Run a training run that is waiting for approval |
POST | /predictive-models/{predictiveId}/training-runs/{runId}/reject | train | Cancel it |
GET | /predictive-models/{predictiveId}/versions | read | List versions with metrics and feature importance |
POST | /predictive-models/{predictiveId}/versions/{versionId}/promote | promote | Make a version current and queue a rescore |
POST | /predictive-models/{predictiveId}/versions/{versionId}/approve-feature | promote | Accept a dominant feature as legitimate |
POST | /predictive-models/{predictiveId}/rescore | train | Start a scoring run with the current version |
GET | /predictive-models/{predictiveId}/scoring-runs | read | The latest 50 scoring runs |
GET | /predictive-models/{predictiveId}/scores | read | A sample of current scores |
GET | /predictive-runs | read | Recent 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
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /features?parent_model_id= | features.read | List features, optionally for one parent model |
POST | /features | features.write | Create a feature |
GET | /features/{featureId} | features.read | Get a feature |
PUT | /features/{featureId} | features.write | Update a feature |
DELETE | /features/{featureId} | features.write | Delete a feature (409 while a model uses it) |
GET | /features/recipe-readiness | models.read | Whether 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
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /rfm-segmentations | read | List segmentations |
POST | /rfm-segmentations | write | Create one (in draft) |
POST | /rfm-segmentations/suggest-monetary-columns | write | Suggest the monetary columns of an event model |
POST | /rfm-segmentations/preflight | write | Check the data a segmentation would read, without saving |
GET | /rfm-segmentations/{configId} | read | Get one |
PUT | /rfm-segmentations/{configId} | write | Update it, including status (draft, active, paused) |
DELETE | /rfm-segmentations/{configId} | write | Delete it; its published model is kept |
POST | /rfm-segmentations/{configId}/run | train | Run it now |
GET | /rfm-segmentations/{configId}/runs | read | The latest 50 runs |
POST | /rfm-segmentations/{configId}/publish | write | Retry 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
| Method | Path | Permission | Description |
|---|---|---|---|
POST | /feature-analysis/run | models.write | Profile a model: {"model_id": "…"} |
GET | /feature-analysis?model_id=&run_id= | models.read | The stored result, latest or a named run; never scans |
GET | /feature-analysis/runs?model_id= | models.read | Past 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.
| Method | Path | Permission | Description |
|---|---|---|---|
GET | /predictive-retention/batches | read | Pending proposals, grouped by version, with the warehouse objects and their sizes |
POST | /predictive-retention/batches/{versionId}/approve | promote | Approve removing that version’s objects |
POST | /predictive-retention/batches/{versionId}/reject | promote | Keep them |
POST | /predictive-retention/registry-orphans/{batchId}/approve | promote | Approve removing an orphaned registry entry |
POST | /predictive-retention/registry-orphans/{batchId}/reject | promote | Keep 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>"