All Products
Search

This Product

    E-MapReduce:GetRayCluster

    Document Center

    E-MapReduce:GetRayCluster

    Last Updated:Apr 10, 2026

    Retrieves the details of a Ray cluster, including its configuration, runtime state, node information, and connection endpoints.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    The table below lists the RAM authorization required to call this API. For details on each column, see RAM authorization.

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    emr-serverless-spark:GetRayCluster

    get

    *All Resource

    *

    		NoneNone

    Request syntax

    GET /api/v1/workspaces/{workspaceId}/rayCluster/{clusterId} HTTP/1.1

    Path Parameters

    Parameter

    Type

    Required

    Description

    Example

    workspaceId

    string

    No

    The workspace ID.

    w-d2d82aa09155

    clusterId

    string

    No

    The cluster ID.

    ray-xxxxxxxxxx

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    No parameters required.

    No parameters required.

    Response elements

    Element

    Type

    Description

    Example

    object

    The response schema.

    requestId

    string

    The request ID.

    DD6B1B2A-5837-5237-ABE4-FF0C8944

    clusterId

    string

    The ID of the Ray cluster.

    ray-k7nm8ahl5te4tg91

    name

    string

    The name of the Ray cluster.

    myRayCluster

    displayReleaseVersion

    string

    The version of the Ray engine.

    ray-1.0.0 (Ray 2.47.1, Python 3.12)

    description

    string

    The description of the Ray cluster.

    Ray Cluster for dev.

    networkServiceName

    string

    The name of the network connection.

    vpc

    headSpec

    object

    The configuration of the head node.

    queueName

    string

    The name of the queue.

    root_queue

    cpu

    string

    The number of CPU cores.

    2

    memory

    string

    The memory size. Unit: Gi.

    8Gi

    enableAutoScaling

    boolean

    Specifies whether auto scaling is enabled for worker nodes.

    false

    idleTimeoutSeconds

    integer

    The idle timeout period for worker nodes, in seconds. Applies only when auto scaling is enabled.

    60

    replica

    integer

    The number of nodes.

    1

    gpuSpec

    string

    ecs.gn6i-c4g1.xlarge

    state

    string

    The session state. Valid values:

    • Starting: The session is starting.

    • Running: The session is running.

    • Stopping: The session is being stopped.

    • Stopped: The session is stopped.

    • Error: The session has failed.

    Running

    creator

    string

    The UID of the user who created the cluster.

    202077646755523991

    creatorName

    string

    The nickname of the creator.

    Alice

    modifier

    string

    The UID of the user who last updated the cluster.

    202077646755523991

    modifierName

    string

    The nickname of the modifier.

    Alice

    userId

    string

    The ID of the Alibaba Cloud account that created the cluster.

    123456789012

    dashboardUrl

    string

    The URL of the Ray Dashboard for this cluster.

    https://emr-ray-gateway-cn-hangzhou.aliyuncs.com/workspace/w-xxxxxxxx/raycluster/ray-xxxxxx/dashboard?token=xxxxxx

    jobUrl

    string

    The public endpoint for submitting Ray jobs.

    https://emr-spark-ray-gateway-cn-hangzhou.aliyuncs.com

    submitToken

    string

    The authentication token for submitting Ray jobs. Add this token to the request header in the format "ray-token": "token".

    1d06484d3b424f7fa4ab7082a4076da2

    modified

    boolean

    Indicates whether the configuration was modified.

    false

    extraParam

    string

    Additional parameters in JSON format.

    {}

    message

    string

    The error message. Returned when state is Error.

    ok

    instances

    array<object>

    The list of nodes in the Ray cluster.

    object

    The details of a Ray cluster node.

    type

    string

    The node type.

    Head

    instanceId

    string

    The node ID.

    ray-uiulpgow9xljim10-head-7cgta

    containerState

    string

    The state of the main container.

    Running

    reason

    string

    Additional information about the node.

    OOMKilled

    phase

    string

    The phase of the node pod.

    Running

    message

    string

    The status message of the node pod.

    ok

    startTime

    integer

    The time when the node started. This is a UNIX timestamp in milliseconds.

    1762946698000

    createTime

    integer

    The time when the node was created. This is a UNIX timestamp in milliseconds.

    1735870116167

    containerStateReason

    string

    Additional information about the main container state.

    ok

    containerStateMessage

    string

    The status message of the main container.

    ContainerExit

    containerExitCode

    integer

    The exit code of the main container.

    137

    instanceId

    string

    The ID of the Ray cluster node.

    ray-k7nm8ahl5te4tg93-xxxxxxx

    workerSpec

    array<object>

    The list of worker node group configurations.

    object

    The configuration of a worker node group.

    groupName

    string

    The name of the worker node group.

    WorkerGroup1

    workerType

    string

    The type of the worker node group.

    CPU

    replica

    integer

    The number of worker nodes.

    2

    queueName

    string

    The name of the queue.

    root_queue

    cpu

    string

    The number of CPU cores per worker node.

    2

    memory

    string

    The memory size per worker node. Unit: Gi.

    8Gi

    minReplica

    integer

    The minimum number of worker nodes in the group.

    1

    maxReplica

    integer

    The maximum number of worker nodes in the group.

    10

    gpuSpec

    string

    ecs.gn6i-c4g1.xlarge

    startTime

    integer

    The time when the cluster started. This is a UNIX timestamp in milliseconds.

    1750327083303

    createTime

    integer

    The time when the cluster was created. This is a UNIX timestamp in milliseconds.

    1750327083303

    modifiedTime

    integer

    The time when the cluster was last updated. This is a UNIX timestamp in milliseconds.

    1754274541693

    grpcEndpoint

    string

    The gRPC endpoint for the internal network. You can also use the domain name in this endpoint to submit Ray jobs.

    ray://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com:80

    volumeIds

    array

    string

    vol-123456789

    jobUrlInner

    string

    http://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com

    Examples

    Success response

    JSON format

    {
  "requestId": "DD6B1B2A-5837-5237-ABE4-FF0C8944",
  "clusterId": "ray-k7nm8ahl5te4tg91",
  "name": "myRayCluster",
  "displayReleaseVersion": "ray-1.0.0 (Ray 2.47.1, Python 3.12)",
  "description": "Ray Cluster for dev.",
  "networkServiceName": "vpc",
  "headSpec": {
    "queueName": "root_queue",
    "cpu": "2",
    "memory": "8Gi",
    "enableAutoScaling": false,
    "idleTimeoutSeconds": 60,
    "replica": 1,
    "gpuSpec": "ecs.gn6i-c4g1.xlarge"
  },
  "state": "Running",
  "creator": "202077646755523991",
  "creatorName": "Alice",
  "modifier": "202077646755523991",
  "modifierName": "Alice",
  "userId": "123456789012",
  "dashboardUrl": "https://emr-ray-gateway-cn-hangzhou.aliyuncs.com/workspace/w-xxxxxxxx/raycluster/ray-xxxxxx/dashboard?token=xxxxxx",
  "jobUrl": "https://emr-spark-ray-gateway-cn-hangzhou.aliyuncs.com",
  "submitToken": "1d06484d3b424f7fa4ab7082a4076da2",
  "modified": false,
  "extraParam": "{}",
  "message": "ok",
  "instances": [
    {
      "type": "Head",
      "instanceId": "ray-uiulpgow9xljim10-head-7cgta",
      "containerState": "Running",
      "reason": "OOMKilled",
      "phase": "Running",
      "message": "ok",
      "startTime": 1762946698000,
      "createTime": 1735870116167,
      "containerStateReason": "ok",
      "containerStateMessage": "ContainerExit",
      "containerExitCode": 137
    }
  ],
  "instanceId": "ray-k7nm8ahl5te4tg93-xxxxxxx",
  "workerSpec": [
    {
      "groupName": "WorkerGroup1",
      "workerType": "CPU",
      "replica": 2,
      "queueName": "root_queue",
      "cpu": "2",
      "memory": "8Gi",
      "minReplica": 1,
      "maxReplica": 10,
      "gpuSpec": "ecs.gn6i-c4g1.xlarge"
    }
  ],
  "startTime": 1750327083303,
  "createTime": 1750327083303,
  "modifiedTime": 1754274541693,
  "grpcEndpoint": "ray://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com:80",
  "volumeIds": [
    "vol-123456789"
  ],
  "jobUrlInner": "http://emr-spark-ray-gateway-cn-hangzhou-internal.emr.aliyuncs.com"
}

    Error codes

    See Error Codes for a complete list.

    See Error codes for a complete list.

    Release notes

    See Release Notes for a complete list.

    See Release notes for a complete list.