REST API Endpoints

All endpoints use the base URL http://localhost:54321 and the /3/ version prefix. Responses are JSON. Long-running operations return a job reference; poll GET /3/Jobs/{job_id} for completion.

Frames

GET /3/Frames

List all frames stored in the H2O cluster.

curl -s http://localhost:54321/3/Frames

Query parameters

query.find_compatible_models

boolean

default:"false"

Include compatible model IDs for each frame.

Response fields

frames

object[]

Array of frame summaries.

Show properties

frame_id

object

Frame key. Use the name field as {frame_id} in subsequent requests.

rows

number

Number of rows.

total_column_count

number

Total number of columns.

columns

object[]

Column metadata including name, type, min, max, mean, and missing count.

GET /3/Frames/

Retrieve details for a specific frame, including column statistics.

curl -s http://localhost:54321/3/Frames/train_frame

Path parameters

path.frame_id

string

required

The key name of the frame (e.g., train_frame).

Query parameters

query.row_offset

number

default:"0"

Starting row for inline data preview.

query.row_count

number

default:"10"

Number of rows to return in the inline preview.

query.column_offset

number

default:"0"

Starting column index.

DELETE /3/Frames/

Delete a frame from the cluster and free its memory.

curl -s -X DELETE http://localhost:54321/3/Frames/train_frame

Frame deletion is irreversible. The data is removed from the distributed key-value store and cannot be recovered.

path.frame_id

string

required

Key name of the frame to delete.

Models

GET /3/Models

List all trained models in the cluster.

curl -s http://localhost:54321/3/Models

Response fields

models

object[]

Array of model summaries.

Show properties

model_id

object

Model key. Use the name field as {model_id} in subsequent requests.

algo

string

Algorithm name (e.g., gbm, drf, deeplearning, glm).

output

object

Training metrics and model output statistics.

GET /3/Models/

Retrieve full details for a specific model, including training metrics and parameters.

curl -s http://localhost:54321/3/Models/GBM_model_1234567890

path.model_id

string

required

The key name of the model (e.g., GBM_model_1234567890).

Response fields

models

object[]

Single-element array containing the model.

Show properties

algo

string

Algorithm used to train the model.

parameters

object

All training parameters, including defaults.

output

object

Training metrics (AUC, logloss, RMSE, etc.), variable importances, and scoring history.

DELETE /3/Models/

Delete a model from the cluster.

curl -s -X DELETE http://localhost:54321/3/Models/GBM_model_1234567890

path.model_id

string

required

Key name of the model to delete.

ModelBuilders

POST /3/ModelBuilders/

Train a model asynchronously. Returns a job reference immediately. The response includes a job.key.name to poll at GET /3/Jobs/{job_id}. Available {algo} values: gbm, drf, deeplearning, glm, gam, xgboost, kmeans, pca, svd, glrm, isolationforest, naivebayes, stackedensemble.

curl -s -X POST http://localhost:54321/3/ModelBuilders/gbm \
  -H "Content-Type: application/json" \
  -d '{
    "training_frame": "train_frame",
    "response_column": {"column_name": "CAPSULE"},
    "ntrees": 100,
    "max_depth": 5,
    "learn_rate": 0.05,
    "seed": 42
  }'

Path parameters

path.algo

string

required

Algorithm name. See the list of available values above.

Common body parameters

body.training_frame

string

required

Key name of the training frame.

body.response_column

object

required

Object with a column_name field specifying the response column (e.g., {"column_name": "label"}).

body.validation_frame

string

Key name of the validation frame.

body.model_id

string

Custom key for the trained model. Auto-generated if omitted.

body.nfolds

number

default:"0"

Cross-validation folds.

body.seed

number

default:"-1"

Random seed.

Response fields

job

object

Asynchronous job reference.

Show properties

key

object

Show properties

name

string

Job ID. Poll GET /3/Jobs/{name} for status.

status

string

Initial status, typically CREATED.

Jobs

GET /3/Jobs/

Poll the status of an asynchronous job.

curl -s http://localhost:54321/3/Jobs/$JOB_KEY

path.job_id

string

required

The job key name returned by a training or parsing request.

Response fields

jobs

object[]

Single-element array with job details.

Show properties

key

object

Job key containing the name field.

status

string

Job state: CREATED, RUNNING, DONE, CANCELLED, FAILED.

progress

number

Completion fraction from 0.0 to 1.0.

progress_msg

string

Human-readable progress description.

start_time

number

Job start time in milliseconds since epoch.

msec

number

Elapsed milliseconds.

dest

object

Destination key of the result (model key, frame key, etc.).

exception

string

Error message if status is FAILED.

Polling loop example:

JOB_KEY="your_job_key_here"

while true; do
  RESPONSE=$(curl -s "http://localhost:54321/3/Jobs/$JOB_KEY")
  STATUS=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['jobs'][0]['status'])")
  PROGRESS=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['jobs'][0]['progress'])")
  echo "Status: $STATUS  Progress: $PROGRESS"
  [ "$STATUS" = "DONE" ] && break
  [ "$STATUS" = "FAILED" ] && echo "Error:" && echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['jobs'][0]['exception'])" && break
  sleep 2
done

AutoML

POST /3/AutoML

Start an AutoML run. Trains multiple models and produces a leaderboard ranked by a performance metric.

curl -s -X POST http://localhost:54321/3/AutoML \
  -H "Content-Type: application/json" \
  -d '{
    "input_spec": {
      "training_frame": "train_frame",
      "response_column": {"column_name": "CAPSULE"}
    },
    "build_control": {
      "stopping_criteria": {
        "max_models": 20,
        "max_runtime_secs": 600
      },
      "seed": 42
    }
  }'

Key body fields

body.input_spec.training_frame

string

required

Key name of the training frame.

body.input_spec.response_column

object

required

Object with column_name field specifying the target column.

body.input_spec.leaderboard_frame

string

Optional holdout frame for leaderboard scoring.

body.build_control.stopping_criteria.max_models

number

Maximum number of individual models to train.

body.build_control.stopping_criteria.max_runtime_secs

number

default:"3600"

Maximum AutoML runtime in seconds.

body.build_control.seed

number

default:"-1"

Random seed. Pair with max_models for reproducible runs.

body.build_spec.exclude_algos

string[]

Algorithms to exclude. Options: GLM, GBM, DRF, XGBoost, DeepLearning, StackedEnsemble.

Response fields

job

object

Job reference for polling. When done, dest.name contains the AutoML project ID.

GET /3/AutoML/

Retrieve the results and leaderboard for a completed AutoML run.

curl -s http://localhost:54321/3/AutoML/AutoML_20240101_120000

path.automl_id

string

required

AutoML project ID, returned in the dest.name field of the job response.

Response fields

leader

object

The best model found. Contains name (model key) and type.

leaderboard

object

Leaderboard frame with all models ranked by the sort metric.

Show properties

name

string

Frame key for the leaderboard data. Retrieve with GET /3/Frames/{name}.

project_name

string

AutoML project identifier.

Predictions

POST /3/Predictions/models//frames/

Score a frame using a trained model. Creates a predictions frame and returns it inline.

curl -s -X POST \
  "http://localhost:54321/3/Predictions/models/GBM_model_1234567890/frames/test_frame"

Path parameters

path.model_id

string

required

Key name of the trained model.

path.frame_id

string

required

Key name of the frame to score.

Query parameters

query.predictions_frame

string

Optional custom key for the output predictions frame.

query.reconstruction_error

boolean

default:"false"

For autoencoder models: return reconstruction error instead of predictions.

query.deep_features_hidden_layer

number

For deep learning models: return activations from a specific hidden layer index.

Response fields

model_metrics

object[]

Performance metrics computed on the scored frame (if the frame has a response column matching the model’s response).

predictions_frame

object

Reference to the output predictions frame.

Show properties

name

string

Frame key. Retrieve predictions with GET /3/Frames/{name}.

Retrieve prediction values:

# Score
curl -s -X POST \
  "http://localhost:54321/3/Predictions/models/GBM_model_1234567890/frames/test_frame" \
  | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['predictions_frame']['name'])"

# Then fetch the predictions frame
PRED_KEY="GBMPredictions_GBM_model_1234567890_test_frame"
curl -s "http://localhost:54321/3/Frames/$PRED_KEY?row_count=5" \
  | python3 -m json.tool

Metadata

GET /3/Metadata/endpoints

List all registered REST endpoints with their HTTP methods, paths, handler classes, and parameter schemas. This is the canonical API discovery endpoint.

curl -s http://localhost:54321/3/Metadata/endpoints | python3 -m json.tool

Response fields

routes

object[]

All registered routes.

Show properties

http_method

string

HTTP method: GET, POST, DELETE, PUT.

url_pattern

string

URL pattern with {param} placeholders.

summary

string

Short description of the endpoint.

input_schema

string

Name of the input schema class.

output_schema

string

Name of the output schema class.

Quick reference

Method	Path	Description
`GET`	`/3/Frames`	List all frames
`GET`	`/3/Frames/{frame_id}`	Get frame details and preview
`DELETE`	`/3/Frames/{frame_id}`	Delete a frame
`GET`	`/3/Models`	List all models
`GET`	`/3/Models/{model_id}`	Get model details and metrics
`DELETE`	`/3/Models/{model_id}`	Delete a model
`POST`	`/3/ModelBuilders/{algo}`	Train a model
`GET`	`/3/Jobs/{job_id}`	Poll job status
`POST`	`/3/AutoML`	Start AutoML
`GET`	`/3/AutoML/{automl_id}`	Get AutoML results
`POST`	`/3/Predictions/models/{model_id}/frames/{frame_id}`	Score a frame
`GET`	`/3/Metadata/endpoints`	List all endpoints
`GET`	`/3/Cloud`	Cluster health and node info
`POST`	`/3/ImportFiles`	Import a file from the server filesystem
`POST`	`/3/Parse`	Parse an imported raw file into a frame
`GET`	`/3/Grid/{grid_id}`	Get grid search results

Python API

R API

REST API

REST API Endpoints

Frames

GET /3/Frames

GET /3/Frames/

DELETE /3/Frames/

Models

GET /3/Models

GET /3/Models/

DELETE /3/Models/

ModelBuilders

POST /3/ModelBuilders/

Jobs

GET /3/Jobs/

AutoML

POST /3/AutoML

GET /3/AutoML/

Predictions

POST /3/Predictions/models//frames/

Metadata

GET /3/Metadata/endpoints

Quick reference

Build docs developers (and LLMs) love

Python API

R API

REST API

​Frames

​GET /3/Frames

​GET /3/Frames/

​DELETE /3/Frames/

​Models

​GET /3/Models

​GET /3/Models/

​DELETE /3/Models/

​ModelBuilders

​POST /3/ModelBuilders/

​Jobs

​GET /3/Jobs/

​AutoML

​POST /3/AutoML

​GET /3/AutoML/

​Predictions

​POST /3/Predictions/models//frames/

​Metadata

​GET /3/Metadata/endpoints

​Quick reference

Build docs developers (and LLMs) love

Frames

GET /3/Frames

GET /3/Frames/

DELETE /3/Frames/

Models

GET /3/Models

GET /3/Models/

DELETE /3/Models/

ModelBuilders

POST /3/ModelBuilders/

Jobs

GET /3/Jobs/

AutoML

POST /3/AutoML

GET /3/AutoML/

Predictions

POST /3/Predictions/models//frames/

Metadata

GET /3/Metadata/endpoints

Quick reference