Ray Jobs REST API specification

This page documents every endpoint of the Ray Jobs REST API, generated from the OpenAPI specification. For request examples and a walkthrough, see Ray Jobs REST API.

GET /api/version

Get Version

Get the Ray Jobs API version and the Ray version running on the cluster.

Response JSON Object:

• version (string) – The version of the Ray Jobs API running on the server.

• ray_version (string) – The version of Ray running on the server.

• ray_commit (string) – The commit of Ray running on the server.

Status Codes:

• 200 OK – The Ray Jobs API version and the Ray version running on the cluster.

POST /api/jobs

Submit Job

Submit a job to the cluster.

Request JSON Object:

• entrypoint (string, required) – Command to start execution, ex: ‘python script.py’

• submission_id (string) – Optional submission_id to specify for the job.

• job_id (string, deprecated) – Optional job_id to specify for the job.

• runtime_env (object) – The runtime environment for the job.

• metadata (object) – Arbitrary user-provided metadata for the job.

• entrypoint_num_cpus (number) – Number of CPUs to allocate for the execution of the entrypoint command, separately from any Ray tasks or actors that are created by it.

• entrypoint_num_gpus (number) – Number of GPUs to allocate for the execution of the entrypoint command, separately from any Ray tasks or actors that are created by it.

• entrypoint_memory (integer) – The quantity of memory to reserve for the execution of the entrypoint command, separately from any tasks or actors launched by it.

• entrypoint_resources (object) – The quantity of various custom resources to allocate for the execution of the entrypoint command, separately from any Ray tasks or actors that are created by it.

Response JSON Object:

• job_id (string, deprecated) – The ID of the submitted job.

• submission_id (string) – The ID of the submitted job.

Status Codes:

• 200 OK – The ID of the submitted job.

• 400 Bad Request – A TypeError or ValueError was raised when submitting the job.

• 500 Internal Server Error – An internal error occurred when submitting the job.

GET /api/jobs

List Jobs

List all submitted jobs in the cluster and their details.

Response JSON Array of Objects:

• type (string:enum) – An enumeration for describing the different job types.

• entrypoint (string, required) – The entrypoint command for this job.

• job_id (string) – The job id. An id that is created for every job that is launched in Ray. This id can be used to fetch data about jobs using Ray core APIs.

• submission_id (string) – A submission id is an id created for every submission job. This id can be used to fetch data about jobs using the job submission APIs.

• driver_info (object) – A class for recording information about the driver related to the job.

• driver_info.id (string, required) – The id of the driver

• driver_info.node_ip_address (string, required) – The ip address of the node the driver is running on

• driver_info.pid (string, required) – The pid of the worker process the driver is using.

• status (string:enum) – An enumeration for describing the status of a job.

• message (string) – A message describing the status in more detail.

• error_type (string) – Internal error, user script error

• start_time (integer) – The time when the job was started. A Unix timestamp in ms.

• end_time (integer) – The time when the job moved into a terminal state. A Unix timestamp in ms.

• metadata (object) – Arbitrary user-provided metadata for the job.

• runtime_env (object) – The runtime environment for the job.

• driver_agent_http_address (string) – Driver agent http address.

• driver_node_id (string) – Driver node id.

Status Codes:

• 200 OK – The details of the jobs.

GET /api/jobs/{submission_id}

Get Job Details

Get the status and details of a job.

Parameters:

• submission_id (string, required) – The ID of the job to get the status and details of.

Response JSON Object:

• type (string:enum) – An enumeration for describing the different job types.

• entrypoint (string, required) – The entrypoint command for this job.

• job_id (string) – The job id. An id that is created for every job that is launched in Ray. This id can be used to fetch data about jobs using Ray core APIs.

• submission_id (string) – A submission id is an id created for every submission job. This id can be used to fetch data about jobs using the job submission APIs.

• driver_info (object) – A class for recording information about the driver related to the job.

• driver_info.id (string, required) – The id of the driver

• driver_info.node_ip_address (string, required) – The ip address of the node the driver is running on

• driver_info.pid (string, required) – The pid of the worker process the driver is using.

• status (string:enum) – An enumeration for describing the status of a job.

• message (string) – A message describing the status in more detail.

• error_type (string) – Internal error, user script error

• start_time (integer) – The time when the job was started. A Unix timestamp in ms.

• end_time (integer) – The time when the job moved into a terminal state. A Unix timestamp in ms.

• metadata (object) – Arbitrary user-provided metadata for the job.

• runtime_env (object) – The runtime environment for the job.

• driver_agent_http_address (string) – Driver agent http address.

• driver_node_id (string) – Driver node id.

Status Codes:

• 200 OK – The details of the job.

• 404 Not Found – The job does not exist.

DELETE /api/jobs/{submission_id}

Delete Job

Delete a job that is already in a terminal state.

Parameters:

• submission_id (string, required) – The ID of the job to cancel.

Status Codes:

• 200 OK – The status of the job.

• 500 Internal Server Error – An internal error occurred when deleting the job, or the job was not in a terminal state.

• 404 Not Found – The job does not exist.

• 400 Bad Request – The job was not submitted via the Ray Jobs API, so it cannot be deleted.

POST /api/jobs/{submission_id}/stop

Stop Job

Stop a job.

Parameters:

• submission_id (string, required) – The ID of the job to stop.

Status Codes:

• 200 OK – The status of the job.

• 500 Internal Server Error – An internal error occurred when stopping the job.

• 404 Not Found – The job does not exist.

• 400 Bad Request – The job was not submitted via the Ray Jobs API, so it cannot be stopped.

GET /api/jobs/{submission_id}/logs

Get Job Logs

Get the logs of a job.

Parameters:

• submission_id (string, required) – The ID of the job to get the logs of.

Response JSON Object:

• logs (string) – The logs of the job.

Status Codes:

• 200 OK – The logs of the job.

• 500 Internal Server Error – An internal error occurred when getting the logs of the job.

• 404 Not Found – The job does not exist.

• 400 Bad Request – The job was not submitted via the Ray Jobs API, so its logs cannot be retrieved.

GET /api/jobs/{submission_id}/logs/tail

Tail Job Logs

WebSocket endpoint for tailing the logs of a job (Not documented in OpenAPI, see https://docs.ray.io/en/latest/_modules/ray/dashboard/modules/job/sdk.html#JobSubmissionClient.tail_job_logs for example usage).

Parameters:

• submission_id (string, required) – The ID of the job to tail the logs of.

Status Codes:

• 404 Not Found – The job does not exist.

• 400 Bad Request – The job was not submitted via the Ray Jobs API, so its logs cannot be retrieved.