Tune Client API¶

You can interact with an ongoing experiment with the Tune Client API. The Tune Client API is organized around REST, which includes resource-oriented URLs, accepts form-encoded requests, returns JSON-encoded responses, and uses standard HTTP protocol.

To allow Tune to receive and respond to your API calls, you have to start your experiment with tune.run(server_port):

tune.run(..., server_port=4321)

The easiest way to use the Tune Client API is with the built-in TuneClient. To use TuneClient, verify that you have the requests library installed:

$ pip install requests

Then, on the client side, you can use the following class. If on a cluster, you may want to forward this port (e.g. ssh -L <local_port>:localhost:<remote_port> <address>) so that you can use the Client on your local machine.

class ray.tune.web_server.TuneClient(tune_address: str, port_forward: int)[source]¶

Client to interact with an ongoing Tune experiment.

Requires a TuneServer to have started running.

tune_address¶

Address of running TuneServer

port_forward¶

Port number of running TuneServer

DeveloperAPI: This API may change across minor Ray releases.

get_all_trials(timeout=None)[source]¶

Returns a list of all trials’ information.

get_trial(trial_id, timeout=None)[source]¶

Returns trial information by trial_id.

add_trial(name, specification)[source]¶

Adds a trial by name and specification (dict).

stop_trial(trial_id)[source]¶

Requests to stop trial by trial_id.

stop_experiment()[source]¶

Requests to stop the entire experiment.

For an example notebook for using the Client API, see the Client API Example.

The API also supports curl. Here are the examples for getting trials (GET /trials/[:id]):

$ curl http://<address>:<port>/trials
$ curl http://<address>:<port>/trials/<trial_id>

And stopping a trial (PUT /trials/:id):

$ curl -X PUT http://<address>:<port>/trials/<trial_id>

previous

Tune Internals

next

Tune CLI (Experimental)