Skip to main content
POST
/
api
/
automl
/
train
Submit an AutoML training job
curl --request POST \
  --url https://api.example.com/api/automl/train \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "domain": "<string>",
  "owner": "<string>",
  "source_table": "<string>",
  "preset": "balanced",
  "label_column": "<string>",
  "positive_class_value": "<unknown>",
  "feature_columns": [
    "<string>"
  ],
  "exclude_columns": [
    "<string>"
  ],
  "group_column": "<string>",
  "action_column": "<string>",
  "reward_column": "<string>",
  "probability_column": "<string>",
  "context_columns": [
    "<string>"
  ],
  "train_split_cutoff": "<string>",
  "time_column": "<string>",
  "hyperparameter_overrides": {},
  "resources": {
    "executor_instances": 2,
    "executor_cores": 2,
    "executor_memory": "8g",
    "executor_memory_overhead": "1g",
    "driver_memory": "4g",
    "driver_cores": 2
  },
  "enable_shap": true,
  "experiment_name": "<string>",
  "registered_model_name": "<string>",
  "feature_engineering_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "trigger_now": true
}
'
{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "domain": "<string>",
  "owner": "<string>",
  "source_table": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "rendered_dag": "<string>",
  "mlflow_run_id": "<string>",
  "mlflow_experiment_name": "<string>",
  "registered_model_name": "<string>",
  "airflow_dag_id": "<string>",
  "airflow_dag_url": "<string>",
  "error_message": "<string>",
  "feature_engineering_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Request to train an AutoML model.

Required fields depend on problem_type. See each field's description for details. Invalid combinations return a 422 validation error.

​
name
string
required

Human-readable training run name.

​
domain
string
required

Business domain for governance.

​
owner
string
required

Username who owns this run.

​
source_table
string
required

Fully qualified Iceberg training table in catalog.schema.table format.

​
problem_type
enum<string>
required

Supervised / unsupervised problem categories.

Available options:
binary_classification,
multiclass_classification,
regression,
ranking,
anomaly_detection,
contextual_bandit
​
algorithm
enum<string>
required

Supported AutoML algorithms.

Available options:
lightgbm_classifier,
lightgbm_regressor,
lightgbm_ranker,
xgboost_classifier,
xgboost_regressor,
xgboost_ranker,
isolation_forest,
vw_classifier,
vw_regressor,
vw_contextual_bandit
​
preset
enum<string>
default:balanced

Tuning presets shared across algorithms.

Available options:
fast,
balanced,
best_quality
​
label_column
string | null
​
positive_class_value
any | null

Value treated as the positive class for binary classification.

​
feature_columns
string[] | null

Override feature columns. If omitted, the job infers features from the table schema, excluding the label, time/group/bandit role columns, and any exclude_columns.

​
exclude_columns
string[] | null

Columns to drop from inferred features. For example, ID columns, entity-grain columns, or columns like trans_num. Ignored when the caller sets feature_columns.

​
group_column
string | null

Group/query identifier for ranking.

​
action_column
string | null
​
reward_column
string | null
​
probability_column
string | null
​
context_columns
string[] | null
​
train_split_cutoff
string | null

Date cutoff string in International Organization for Standardization (ISO) 8601 format. Rows with the time column before the cutoff go to train, those at or after go to test. Defaults to an 80/20 random split when omitted.

​
time_column
string | null

Column used by train_split_cutoff. Required when you configure train_split_cutoff.

​
hyperparameter_overrides
Hyperparameter Overrides · object | null
​
resources
SparkResourceSpec · object | null

Optional Spark resource overrides for the training DAG.

Any field you omit auto-sizes from the dataset's row count, byte size, and feature width via automl_resource_sizing. A field you provide always wins over the derived value. Memory follows Spark's <n>g / <n>m format. For example, "8g".

​
enable_shap
boolean
default:true
​
experiment_name
string | null
​
registered_model_name
string | null
​
feature_engineering_job_id
string<uuid> | null
​
trigger_now
boolean
default:true

Response

Job created with rendered DAG.

A persisted training job.

​
job_id
string<uuid>
required
​
name
string
required
​
domain
string
required
​
owner
string
required
​
source_table
string
required
​
problem_type
enum<string>
required

Supervised / unsupervised problem categories.

Available options:
binary_classification,
multiclass_classification,
regression,
ranking,
anomaly_detection,
contextual_bandit
​
algorithm
enum<string>
required

Supported AutoML algorithms.

Available options:
lightgbm_classifier,
lightgbm_regressor,
lightgbm_ranker,
xgboost_classifier,
xgboost_regressor,
xgboost_ranker,
isolation_forest,
vw_classifier,
vw_regressor,
vw_contextual_bandit
​
preset
enum<string>
required

Tuning presets shared across algorithms.

Available options:
fast,
balanced,
best_quality
​
status
enum<string>
required

Lifecycle of an AutoML training job.

  • READY: DAG uploaded but not yet triggered. The user opted out of auto-trigger at create time. Manual trigger flips it to QUEUED.
  • QUEUED: DAG triggered, waiting for Airflow to pick it up.
  • RUNNING: Airflow has the run going.
  • COMPLETE/FAILED: terminal.
Available options:
ready,
queued,
running,
complete,
failed
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
rendered_dag
string | null

The rendered DAG source. Populated on creation.

​
mlflow_run_id
string | null
​
mlflow_experiment_name
string | null
​
registered_model_name
string | null
​
airflow_dag_id
string | null
​
airflow_dag_url
string | null
​
error_message
string | null
​
feature_engineering_job_id
string<uuid> | null