Start Training

Page Outline

• Path Parameters
• Request Body
• Behavior
• Response

---

Triggers a new training run for a model using the current active configuration and linked dataset.

Base Path: /api/v1/models

Method: POST

Path: /{model_id}/train

Auth: Requires a valid Bearer token (Authorization: Bearer <JWT>)

Path Parameters

Parameter	Type	Description
model_id	string	Unique identifier of the model to train

Request Body

{
  "config_override": {
    "algorithm": "lightgbm",
    "hyperparameters": {
      "n_estimators": 300
    }
  },
  "run_label": "experiment-lightgbm-v1",
  "priority": "high",
  "timeout_seconds": 7200
}

Field	Type	Required	Description
config_override	object	❌	Temporary config overrides applied only for this run (does not modify the saved config)
run_label	string	❌	Human-readable label for this training run
priority	string	❌	Queue priority: low, normal, high (default: normal)
timeout_seconds	integer	❌	Max allowed training duration before auto-cancellation (default: 3600)

Behavior

• Fails with HTTP 409 if a training run is already in progress for this model.
• Fails with HTTP 422 if no dataset is linked or if the config is missing required fields (target_column, feature_columns).
• For model_type: "custom", requires that custom assets have been uploaded before training can start.
• Enqueues the training job in the orchestration system; actual training begins asynchronously once a worker is available.
• Model status transitions to training immediately upon a successful request.
• An audit log entry is written with action model.training_started, including the training run ID.
• Poll training progress via the Get Metrics or Get Details endpoints.

Response

Returns a TrainingRun object confirming job creation.

{
  "run_id": "run-20260313-a4b9c2",
  "model_id": "mdl-7f3a19bc",
  "status": "queued",
  "run_label": "experiment-lightgbm-v1",
  "priority": "high",
  "estimated_start_time": "2026-03-13T16:20:00Z",
  "created_at": "2026-03-13T16:10:00Z"
}