Create training job

curl --request POST \
  --url https://api.example.com/v1/training_jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataframe": {
    "plan": {},
    "columns": [
      {
        "name": "<string>",
        "datatype": {
          "kind": "string"
        }
      }
    ],
    "version": 1
  },
  "job_tags": {},
  "task": {
    "label_column": "<string>",
    "task_kind": "regression"
  },
  "hpo_space": {
    "models": [
      {
        "family": "<string>",
        "search": {},
        "fixed": {}
      }
    ]
  },
  "metrics": [
    "<string>"
  ],
  "optimizer": {
    "kind": "tpe",
    "n_trials_per_step": 2,
    "n_steps": 2
  },
  "n_cv_splits": 123,
  "ensemble": false,
  "random_state": 42
}
'

import requests

url = "https://api.example.com/v1/training_jobs"

payload = {
    "dataframe": {
        "plan": {},
        "columns": [
            {
                "name": "<string>",
                "datatype": { "kind": "string" }
            }
        ],
        "version": 1
    },
    "job_tags": {},
    "task": {
        "label_column": "<string>",
        "task_kind": "regression"
    },
    "hpo_space": { "models": [
            {
                "family": "<string>",
                "search": {},
                "fixed": {}
            }
        ] },
    "metrics": ["<string>"],
    "optimizer": {
        "kind": "tpe",
        "n_trials_per_step": 2,
        "n_steps": 2
    },
    "n_cv_splits": 123,
    "ensemble": False,
    "random_state": 42
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dataframe: {
      plan: {},
      columns: [{name: '<string>', datatype: {kind: 'string'}}],
      version: 1
    },
    job_tags: {},
    task: {label_column: '<string>', task_kind: 'regression'},
    hpo_space: {models: [{family: '<string>', search: {}, fixed: {}}]},
    metrics: ['<string>'],
    optimizer: {kind: 'tpe', n_trials_per_step: 2, n_steps: 2},
    n_cv_splits: 123,
    ensemble: false,
    random_state: 42
  })
};

fetch('https://api.example.com/v1/training_jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/training_jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dataframe' => [
        'plan' => [
                
        ],
        'columns' => [
                [
                                'name' => '<string>',
                                'datatype' => [
                                                                'kind' => 'string'
                                ]
                ]
        ],
        'version' => 1
    ],
    'job_tags' => [
        
    ],
    'task' => [
        'label_column' => '<string>',
        'task_kind' => 'regression'
    ],
    'hpo_space' => [
        'models' => [
                [
                                'family' => '<string>',
                                'search' => [
                                                                
                                ],
                                'fixed' => [
                                                                
                                ]
                ]
        ]
    ],
    'metrics' => [
        '<string>'
    ],
    'optimizer' => [
        'kind' => 'tpe',
        'n_trials_per_step' => 2,
        'n_steps' => 2
    ],
    'n_cv_splits' => 123,
    'ensemble' => false,
    'random_state' => 42
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/training_jobs"

	payload := strings.NewReader("{\n  \"dataframe\": {\n    \"plan\": {},\n    \"columns\": [\n      {\n        \"name\": \"<string>\",\n        \"datatype\": {\n          \"kind\": \"string\"\n        }\n      }\n    ],\n    \"version\": 1\n  },\n  \"job_tags\": {},\n  \"task\": {\n    \"label_column\": \"<string>\",\n    \"task_kind\": \"regression\"\n  },\n  \"hpo_space\": {\n    \"models\": [\n      {\n        \"family\": \"<string>\",\n        \"search\": {},\n        \"fixed\": {}\n      }\n    ]\n  },\n  \"metrics\": [\n    \"<string>\"\n  ],\n  \"optimizer\": {\n    \"kind\": \"tpe\",\n    \"n_trials_per_step\": 2,\n    \"n_steps\": 2\n  },\n  \"n_cv_splits\": 123,\n  \"ensemble\": false,\n  \"random_state\": 42\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/training_jobs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dataframe\": {\n    \"plan\": {},\n    \"columns\": [\n      {\n        \"name\": \"<string>\",\n        \"datatype\": {\n          \"kind\": \"string\"\n        }\n      }\n    ],\n    \"version\": 1\n  },\n  \"job_tags\": {},\n  \"task\": {\n    \"label_column\": \"<string>\",\n    \"task_kind\": \"regression\"\n  },\n  \"hpo_space\": {\n    \"models\": [\n      {\n        \"family\": \"<string>\",\n        \"search\": {},\n        \"fixed\": {}\n      }\n    ]\n  },\n  \"metrics\": [\n    \"<string>\"\n  ],\n  \"optimizer\": {\n    \"kind\": \"tpe\",\n    \"n_trials_per_step\": 2,\n    \"n_steps\": 2\n  },\n  \"n_cv_splits\": 123,\n  \"ensemble\": false,\n  \"random_state\": 42\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/training_jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dataframe\": {\n    \"plan\": {},\n    \"columns\": [\n      {\n        \"name\": \"<string>\",\n        \"datatype\": {\n          \"kind\": \"string\"\n        }\n      }\n    ],\n    \"version\": 1\n  },\n  \"job_tags\": {},\n  \"task\": {\n    \"label_column\": \"<string>\",\n    \"task_kind\": \"regression\"\n  },\n  \"hpo_space\": {\n    \"models\": [\n      {\n        \"family\": \"<string>\",\n        \"search\": {},\n        \"fixed\": {}\n      }\n    ]\n  },\n  \"metrics\": [\n    \"<string>\"\n  ],\n  \"optimizer\": {\n    \"kind\": \"tpe\",\n    \"n_trials_per_step\": 2,\n    \"n_steps\": 2\n  },\n  \"n_cv_splits\": 123,\n  \"ensemble\": false,\n  \"random_state\": 42\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

training

Create training job

Compile the training graph and hand it to the scheduler.

The router’s responsibility ends at “ship the DTO”: validate the request (RBAC + spec coherence), build the dataset and check it against the caller’s role-shape limits, then hand the built dataset to :func:_submit_training_run, which compiles the graph, cloudpickles the context to S3, and puts a :class:RequestToComputeGraph on the in-process inbox. The scheduler owns the jobs and computation_node tables and INSERTs both atomically; the router awaits the one-shot reply future on the submission for the minted job_id and returns that resource id.

All validation/assertion lives here, before the submit — the submit step only submits.

POST

training_jobs

Create training job

curl --request POST \
  --url https://api.example.com/v1/training_jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataframe": {
    "plan": {},
    "columns": [
      {
        "name": "<string>",
        "datatype": {
          "kind": "string"
        }
      }
    ],
    "version": 1
  },
  "job_tags": {},
  "task": {
    "label_column": "<string>",
    "task_kind": "regression"
  },
  "hpo_space": {
    "models": [
      {
        "family": "<string>",
        "search": {},
        "fixed": {}
      }
    ]
  },
  "metrics": [
    "<string>"
  ],
  "optimizer": {
    "kind": "tpe",
    "n_trials_per_step": 2,
    "n_steps": 2
  },
  "n_cv_splits": 123,
  "ensemble": false,
  "random_state": 42
}
'

import requests

url = "https://api.example.com/v1/training_jobs"

payload = {
    "dataframe": {
        "plan": {},
        "columns": [
            {
                "name": "<string>",
                "datatype": { "kind": "string" }
            }
        ],
        "version": 1
    },
    "job_tags": {},
    "task": {
        "label_column": "<string>",
        "task_kind": "regression"
    },
    "hpo_space": { "models": [
            {
                "family": "<string>",
                "search": {},
                "fixed": {}
            }
        ] },
    "metrics": ["<string>"],
    "optimizer": {
        "kind": "tpe",
        "n_trials_per_step": 2,
        "n_steps": 2
    },
    "n_cv_splits": 123,
    "ensemble": False,
    "random_state": 42
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    dataframe: {
      plan: {},
      columns: [{name: '<string>', datatype: {kind: 'string'}}],
      version: 1
    },
    job_tags: {},
    task: {label_column: '<string>', task_kind: 'regression'},
    hpo_space: {models: [{family: '<string>', search: {}, fixed: {}}]},
    metrics: ['<string>'],
    optimizer: {kind: 'tpe', n_trials_per_step: 2, n_steps: 2},
    n_cv_splits: 123,
    ensemble: false,
    random_state: 42
  })
};

fetch('https://api.example.com/v1/training_jobs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/training_jobs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dataframe' => [
        'plan' => [
                
        ],
        'columns' => [
                [
                                'name' => '<string>',
                                'datatype' => [
                                                                'kind' => 'string'
                                ]
                ]
        ],
        'version' => 1
    ],
    'job_tags' => [
        
    ],
    'task' => [
        'label_column' => '<string>',
        'task_kind' => 'regression'
    ],
    'hpo_space' => [
        'models' => [
                [
                                'family' => '<string>',
                                'search' => [
                                                                
                                ],
                                'fixed' => [
                                                                
                                ]
                ]
        ]
    ],
    'metrics' => [
        '<string>'
    ],
    'optimizer' => [
        'kind' => 'tpe',
        'n_trials_per_step' => 2,
        'n_steps' => 2
    ],
    'n_cv_splits' => 123,
    'ensemble' => false,
    'random_state' => 42
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/training_jobs"

	payload := strings.NewReader("{\n  \"dataframe\": {\n    \"plan\": {},\n    \"columns\": [\n      {\n        \"name\": \"<string>\",\n        \"datatype\": {\n          \"kind\": \"string\"\n        }\n      }\n    ],\n    \"version\": 1\n  },\n  \"job_tags\": {},\n  \"task\": {\n    \"label_column\": \"<string>\",\n    \"task_kind\": \"regression\"\n  },\n  \"hpo_space\": {\n    \"models\": [\n      {\n        \"family\": \"<string>\",\n        \"search\": {},\n        \"fixed\": {}\n      }\n    ]\n  },\n  \"metrics\": [\n    \"<string>\"\n  ],\n  \"optimizer\": {\n    \"kind\": \"tpe\",\n    \"n_trials_per_step\": 2,\n    \"n_steps\": 2\n  },\n  \"n_cv_splits\": 123,\n  \"ensemble\": false,\n  \"random_state\": 42\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/training_jobs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dataframe\": {\n    \"plan\": {},\n    \"columns\": [\n      {\n        \"name\": \"<string>\",\n        \"datatype\": {\n          \"kind\": \"string\"\n        }\n      }\n    ],\n    \"version\": 1\n  },\n  \"job_tags\": {},\n  \"task\": {\n    \"label_column\": \"<string>\",\n    \"task_kind\": \"regression\"\n  },\n  \"hpo_space\": {\n    \"models\": [\n      {\n        \"family\": \"<string>\",\n        \"search\": {},\n        \"fixed\": {}\n      }\n    ]\n  },\n  \"metrics\": [\n    \"<string>\"\n  ],\n  \"optimizer\": {\n    \"kind\": \"tpe\",\n    \"n_trials_per_step\": 2,\n    \"n_steps\": 2\n  },\n  \"n_cv_splits\": 123,\n  \"ensemble\": false,\n  \"random_state\": 42\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/training_jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dataframe\": {\n    \"plan\": {},\n    \"columns\": [\n      {\n        \"name\": \"<string>\",\n        \"datatype\": {\n          \"kind\": \"string\"\n        }\n      }\n    ],\n    \"version\": 1\n  },\n  \"job_tags\": {},\n  \"task\": {\n    \"label_column\": \"<string>\",\n    \"task_kind\": \"regression\"\n  },\n  \"hpo_space\": {\n    \"models\": [\n      {\n        \"family\": \"<string>\",\n        \"search\": {},\n        \"fixed\": {}\n      }\n    ]\n  },\n  \"metrics\": [\n    \"<string>\"\n  ],\n  \"optimizer\": {\n    \"kind\": \"tpe\",\n    \"n_trials_per_step\": 2,\n    \"n_steps\": 2\n  },\n  \"n_cv_splits\": 123,\n  \"ensemble\": false,\n  \"random_state\": 42\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

An API key or OAuth2/OIDC access token sent as Authorization: Bearer <token>.

Body

application/json

dataframe

WireDataFrame · object

required

Serialized DataFrame plan over the org's registered sources. The server rebuilds the org's Context, deserializes this against it, and materializes the (possibly filtered/derived) training rows. The leaf source must be a registered source_table.

Show child attributes

job_tags

Job Tags · object

Caller-supplied tags echoed on the training job resource.

Show child attributes

task

Regression · object

Learning task and its target columns (a discriminated union on task_kind). Required for supervised training.

Show child attributes

hpo_space

HPOSpace · object | null

The search space: candidate model families and, per family, which hyperparameters are fixed vs searched (Float/Int/Categorical/Mixture). If omitted, the server picks a default space based on dataset shape.

Show child attributes

metrics

string[] | null

Metric names to optimise, e.g. ['auc'] or ['auc', 'neg_class_error']. A list of metrics is optimised jointly via Optuna's native multi-objective (Pareto) search, with no metric privileged. Custom Python callables are not supported in v1.

optimizer

Optimizer · object | null

How to search the space: sampler ('tpe'/'random'/'cmaes') and a round-structured trial budget (n_trials_per_step proposed per round x n_steps rounds). If omitted, the server uses a default optimizer.

Show child attributes

n_cv_splits

integer | null

K-fold cross-validation folds. None means a single holdout split.

ensemble

boolean

default:false

If true, build a Caruana-style ensemble across stage-1 fold/trial models instead of refitting the winner on full data.

random_state

integer

default:42

Response

Successful Response

required

List training jobs Get training job

connector

source_tables

training

reasoning

jobs

models

inference

materialize

serving

system

Create training job

Authorizations

Body

Response