Clusters API

The Clusters API allows you to create, start, edit, list, terminate, and delete clusters. The maximum allowed size of a request to the Clusters API is 10MB.

Cluster lifecycle methods require a cluster ID, which is returned from Create. To obtain a list of clusters, invoke List.

Azure Databricks maps cluster node instance types to compute units known as DBUs. See the instance type pricing page for a list of the supported instance types and their corresponding DBUs. For instance provider information, see Azure instance type specifications and pricing.

Azure Databricks always provides one year’s deprecation notice before ceasing support for an instance type.

Important

To access Databricks REST APIs, you must authenticate.

Create

Endpoint HTTP Method
2.0/clusters/create POST

Create a new Apache Spark cluster. This method acquires new instances from the cloud provider if necessary. This method is asynchronous; the returned cluster_id can be used to poll the cluster state. When this method returns, the cluster is in a PENDING state. The cluster is usable once it enters a RUNNING state. See ClusterState.

Note

Azure Databricks may not be able to acquire some of the requested nodes, due to cloud provider limitations or transient network issues. If it is unable to acquire a sufficient number of the requested nodes, cluster creation will terminate with an informative error message.

An example request:

{
  "cluster_name": "my-cluster",
  "spark_version": "5.3.x-scala2.11",
  "node_type_id": "Standard_D3_v2",
  "spark_conf": {
    "spark.speculation": true
  },
  "num_workers": 25
}

Here is an example for an autoscaling cluster. This cluster will start with 2 nodes, the minimum.

{
  "cluster_name": "autoscaling-cluster",
  "spark_version": "5.3.x-scala2.11",
  "node_type_id": "Standard_D3_v2",
  "autoscale" : {
    "min_workers": 2,
    "max_workers": 50
  }
}

Here is an example that includes the policy to use.

{
    "num_workers": null,
    "autoscale": {
        "min_workers": 2,
        "max_workers": 8
    },
    "cluster_name": "my-cluster",
    "spark_version": "6.2.x-scala2.11",
    "spark_conf": {},
    "node_type_id": "Standard_D3_v2",
    "custom_tags": {},
    "spark_env_vars": {
        "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "autotermination_minutes": 120,
    "init_scripts": [],
    "policy_id": "C65B864F02000008"
}

Create a job using a policy with the API

To create a job or submit a run with a new cluster using a policy, add the policy_id attribute to the request’s new_cluster specification.

{
  "run_name": "my spark task",
  "new_cluster": {
    "spark_version": "6.0.x-scala2.11",
    "node_type_id": "Standard_D3_v2",
    "num_workers": 10,
    "policy_id": "ABCD000000000000"
  },
  "spark_jar_task": {
    "main_class_name": "com.databricks.ComputeModels"
  }
}

Request structure

Field Name Type Description
num_workers OR autoscale INT32 OR AutoScale If num_workers, number of worker nodes that this cluster should have. A cluster has one Spark driver and num_workers executors for a total of num_workers + 1 Spark nodes.

Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas the workers listed in executors will gradually increase from 5 to 10 as the new nodes are provisioned.

If autoscale, parameters needed in order to automatically scale clusters up and down based on load.
cluster_name STRING Cluster name requested by the user. This doesn’t have to be unique. If not specified at creation, the cluster name will be an empty string.
spark_version STRING The runtime version of the cluster. You can retrieve a list of available runtime versions by using the Runtime versions API call. This field is required.
spark_conf SparkConfPair An object containing a set of optional, user-specified Spark configuration key-value pairs. You can also pass in a string of extra JVM options to the driver and the executors via
spark.driver.extraJavaOptions and spark.executor.extraJavaOptions respectively.

Example Spark confs:
{"spark.speculation": true, "spark.streaming.ui.retainedBatches": 5} or
{"spark.driver.extraJavaOptions": "-verbose:gc -XX:+PrintGCDetails"}
node_type_id STRING This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute intensive workloads A list of available node types can be retrieved by using the List node types API call. This field is required.
driver_node_type_id STRING The node type of the Spark driver. This field is optional; if unset, the driver node type will be set as the same value as node_type_id defined above.
custom_tags ClusterTag An object containing a set of tags for cluster resources. Databricks tags all cluster resources (e.g., VMs ) with these tags in addition to default_tags.

Note:

Azure Databricks allows at most 43 custom tags.
cluster_log_conf ClusterLogConf The configuration for delivering Spark logs to a long-term storage destination. Only one destination can be specified for one cluster. If the conf is given, the logs will be delivered to the destination every
5 mins. The destination of driver logs is <destination>/<cluster-ID>/driver, while the destination of executor logs is <destination>/<cluster-ID>/executor.
init_scripts An array of InitScriptInfo The configuration for storing init scripts. Any number of scripts can be specified. The scripts are executed sequentially in the order provided. If cluster_log_conf is specified, init script logs are sent to
<destination>/<cluster-ID>/init_scripts.
docker_image DockerImage Docker image for a custom container.
spark_env_vars SparkEnvPair An object containing a set of optional, user-specified environment variable key-value pairs. Key-value pairs of the form (X,Y) are exported as is (i.e.,
export X='Y') while launching the driver and workers.

In order to specify an additional set of SPARK_DAEMON_JAVA_OPTS, we recommend appending them to $SPARK_DAEMON_JAVA_OPTS as shown in the following example. This ensures that all default databricks managed environmental variables are included as well.

Example Spark environment variables:
{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"} or
{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}
autotermination_minutes INT32 Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this cluster will not be automatically terminated. If specified, the threshold must be between 10 and 10000 minutes. You can also set this value to 0 to explicitly disable automatic termination.
instance_pool_id STRING The optional ID of the instance pool to which the cluster belongs. Refer to Instance Pools API for details.
idempotency_token STRING An optional token that can be used to guarantee the idempotency of cluster creation requests. If an active cluster with the provided token already exists, the request will not create a new cluster, but it will return the ID of the existing cluster instead. The existence of a cluster with the same token is not checked against terminated clusters.

If you specify the idempotency token, upon failure you can retry until the request succeeds. Azure Databricks will guarantee that exactly one cluster will be launched with that idempotency token.

This token should have at most 64 characters.

Response structure

Field Name Type Description
cluster_id STRING Canonical identifier for the cluster.

Edit

Endpoint HTTP Method
2.0/clusters/edit POST

Edit the configuration of a cluster to match the provided attributes and size.

You can edit a cluster if it is in a RUNNING or TERMINATED state. If you edit a cluster while it is in a RUNNING state, it will be restarted so that the new attributes can take effect. If you edit a cluster while it is in a TERMINATED state, it will remain TERMINATED. The next time it is started using the clusters/start API, the new attributes will take effect. An attempt to edit a cluster in any other state will be rejected with an INVALID_STATE error code.

Clusters created by the Databricks Jobs service cannot be edited.

An example request:

{
 "cluster_id": "1202-211320-brick1",
 "num_workers": 10,
 "spark_version": "5.3.x-scala2.11",
 "node_type_id": "Standard_D3_v2"
}

Request structure

Field Name Type Description
num_workers OR autoscale INT32 OR AutoScale If num_workers, number of worker nodes that this cluster should have. A cluster has one Spark driver and num_workers executors for a total of num_workers + 1 Spark nodes.

Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas the workers listed in executors will gradually increase from 5 to 10 as the new nodes are provisioned.

If autoscale, parameters needed in order to automatically scale clusters up and down based on load.
cluster_id STRING Canonical identifier for the cluster. This field is required.
cluster_name STRING Cluster name requested by the user. This doesn’t have to be unique. If not specified at creation, the cluster name will be an empty string.
spark_version STRING The runtime version of the cluster. You can retrieve a list of available runtime versions by using the Runtime versions API call. This field is required.
spark_conf SparkConfPair An object containing a set of optional, user-specified Spark configuration key-value pairs. You can also pass in a string of extra JVM options to the driver and the executors via
spark.driver.extraJavaOptions and spark.executor.extraJavaOptions respectively.

Example Spark confs:
{"spark.speculation": true, "spark.streaming.ui.retainedBatches": 5} or
{"spark.driver.extraJavaOptions": "-verbose:gc -XX:+PrintGCDetails"}
node_type_id STRING This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute intensive workloads A list of available node types can be retrieved by using the List node types API call. This field is required.
driver_node_type_id STRING The node type of the Spark driver. This field is optional; if unset, the driver node type will be set as the same value as node_type_id defined above.
cluster_log_conf ClusterLogConf The configuration for delivering Spark logs to a long-term storage destination. Only one destination can be specified for one cluster. If the conf is given, the logs will be delivered to the destination every
5 mins. The destination of driver logs is <destination>/<cluster-ID>/driver, while the destination of executor logs is <destination>/<cluster-ID>/executor.
init_scripts An array of InitScriptInfo The configuration for storing init scripts. Any number of destinations can be specified. The scripts are executed sequentially in the order provided. If cluster_log_conf is specified, init script logs are sent to
<destination>/<cluster-ID>/init_scripts.
docker_image DockerImage Docker image for a custom container.
spark_env_vars SparkEnvPair An object containing a set of optional, user-specified environment variable key-value pairs. Key-value pairs of the form (X,Y) are exported as is (i.e.,
export X='Y') while launching the driver and workers.

In order to specify an additional set of SPARK_DAEMON_JAVA_OPTS, we recommend appending them to $SPARK_DAEMON_JAVA_OPTS as shown in the following example. This ensures that all default databricks managed environmental variables are included as well.

Example Spark environment variables:
{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"} or
{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}
autotermination_minutes INT32 Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this cluster will not be automatically terminated. If specified, the threshold must be between 10 and 10000 minutes. You can also set this value to 0 to explicitly disable automatic termination.
instance_pool_id STRING The optional ID of the instance pool to which the cluster belongs. Refer to Pools for details.

Start

Endpoint HTTP Method
2.0/clusters/start POST

Start a terminated cluster given its ID. This is similar to createCluster, except:

  • The terminated cluster ID and attributes are preserved.
  • The cluster starts with the last specified cluster size. If the terminated cluster is an autoscaling cluster, the cluster starts with the minimum number of nodes.
  • If the cluster is in the RESTARTING state, a 400 error is returned.
  • You cannot start a cluster launched to run a job.

An example request:

{
  "cluster_id": "1202-211320-brick1"
}

Request structure

Field Name Type Description
cluster_id STRING The cluster to be started. This field is required.

Restart

Endpoint HTTP Method
2.0/clusters/restart POST

Restart a cluster given its ID. The cluster must be in the RUNNING state.

An example request:

{
  "cluster_id": "1202-211320-brick1"
}

Request structure

Field Name Type Description
cluster_id STRING The cluster to be started. This field is required.

Resize

Endpoint HTTP Method
2.0/clusters/resize POST

Resize a cluster to have a desired number of workers. The cluster must be in the RUNNING state.

An example request:

{
  "cluster_id": "1202-211320-brick1",
  "num_workers": 30
}

Request structure

Field Name Type Description
num_workers OR autoscale INT32 OR AutoScale If num_workers, number of worker nodes that this cluster should have. A cluster has one Spark driver and num_workers executors for a total of num_workers + 1 Spark nodes.

Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas the workers listed in executors will gradually increase from 5 to 10 as the new nodes are provisioned.

If autoscale, parameters needed in order to automatically scale clusters up and down based on load.
cluster_id STRING The cluster to be resized. This field is required.

Delete (terminate)

Endpoint HTTP Method
2.0/clusters/delete POST

Terminate a cluster given its ID. The cluster is removed asynchronously. Once the termination has completed, the cluster will be in the TERMINATED state. If the cluster is already in a TERMINATING or TERMINATED state, nothing will happen.

30 days after a cluster is terminated, it is permanently deleted.

An example request:

{
  "cluster_id": "1202-211320-brick1"
}

Request structure

Field Name Type Description
cluster_id STRING The cluster to be terminated. This field is required.

Permanent delete

Endpoint HTTP Method
2.0/clusters/permanent-delete POST

Permanently delete a cluster. If the cluster is running, it is terminated and its resources are asynchronously removed. If the cluster is terminated, then it is immediately removed.

You cannot perform any action, including retrieve the cluster’s permissions, on a permanently deleted cluster. A permanently deleted cluster is also no longer returned in the cluster list.

An example request:

{
  "cluster_id": "1202-211320-brick1"
}

Request structure

Field Name Type Description
cluster_id STRING The cluster to be permanently deleted. This field is required.

Get

Endpoint HTTP Method
2.0/clusters/get GET

Retrieve the information for a cluster given its identifier. Clusters can be described while they are running or up to 30 days after they are terminated.

An example request:

/clusters/get?cluster_id=1202-211320-brick1

Request structure

Field Name Type Description
cluster_id STRING The cluster about which to retrieve information. This field is required.

Response structure

Field Name Type Description
num_workers OR autoscale INT32 OR AutoScale If num_workers, number of worker nodes that this cluster should have. A cluster has one Spark driver and num_workers executors for a total of num_workers + 1 Spark nodes.

Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas the workers listed in executors will gradually increase from 5 to 10 as the new nodes are provisioned.

If autoscale, parameters needed in order to automatically scale clusters up and down based on load.
cluster_id STRING Canonical identifier for the cluster. This ID is retained during cluster restarts and resizes, while each new cluster has a globally unique ID.
creator_user_name STRING Creator user name. The field won’t be included in the response if the user has already been deleted.
driver SparkNode Node on which the Spark driver resides. The driver node contains the Spark master and the Databricks application that manages the per-notebook Spark REPLs.
executors An array of SparkNode Nodes on which the Spark executors reside.
spark_context_id INT64 A canonical SparkContext identifier. This value does change when the Spark driver restarts. The pair (cluster_id, spark_context_id) is a globally unique identifier over all Spark contexts.
jdbc_port INT32 Port on which Spark JDBC server is listening in the driver node. No service will be listening on on this port in executor nodes.
cluster_name STRING Cluster name requested by the user. This doesn’t have to be unique. If not specified at creation, the cluster name will be an empty string.
spark_version STRING The runtime version of the cluster. You can retrieve a list of available runtime versions by using the Runtime versions API call.
spark_conf SparkConfPair An object containing a set of optional, user-specified Spark configuration key-value pairs. You can also pass in a string of extra JVM options to the driver and the executors via
spark.driver.extraJavaOptions and spark.executor.extraJavaOptions respectively.

Example Spark confs:
{"spark.speculation": true, "spark.streaming.ui.retainedBatches": 5} or
{"spark.driver.extraJavaOptions": "-verbose:gc -XX:+PrintGCDetails"}
node_type_id STRING This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute intensive workloads A list of available node types can be retrieved by using the List node types API call. This field is required.
driver_node_type_id STRING The node type of the Spark driver. This field is optional; if unset, the driver node type will be set as the same value as node_type_id defined above.
custom_tags ClusterTag An object containing a set of tags for cluster resources. Databricks tags all cluster resources with these tags in addition to default_tags.

Note:

* Tags are not supported on legacy node types such as compute-optimized and memory-optimized
* Databricks allows at most 45 custom tags
cluster_log_conf ClusterLogConf The configuration for delivering Spark logs to a long-term storage destination. Only one destination can be specified for one cluster. If the conf is given, the logs will be delivered to the destination every
5 mins. The destination of driver logs is <destination>/<cluster-ID>/driver, while the destination of executor logs is <destination>/<cluster-ID>/executor.
init_scripts An array of InitScriptInfo The configuration for storing init scripts. Any number of destinations can be specified. The scripts are executed sequentially in the order provided. If cluster_log_conf is specified, init script logs are sent to
<destination>/<cluster-ID>/init_scripts.
docker_image DockerImage Docker image for a custom container.
spark_env_vars SparkEnvPair An object containing a set of optional, user-specified environment variable key-value pairs. Key-value pairs of the form (X,Y) are exported as is (i.e.,
export X='Y') while launching the driver and workers.

In order to specify an additional set of SPARK_DAEMON_JAVA_OPTS, we recommend appending them to $SPARK_DAEMON_JAVA_OPTS as shown in the following example. This ensures that all default databricks managed environmental variables are included as well.

Example Spark environment variables:
{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"} or
{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}
autotermination_minutes INT32 Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this cluster will not be automatically terminated. If specified, the threshold must be between 10 and 10000 minutes. You can also set this value to 0 to explicitly disable automatic termination.
enable_elastic_disk BOOL Autoscaling Local Storage: when enabled, this cluster will dynamically acquire additional disk space when its Spark workers are running low on disk space. See Autoscaling local storage for details.
instance_pool_id STRING The optional ID of the instance pool to which the cluster belongs. Refer to Pools for details.
state ClusterState State of the cluster.
state_message STRING A message associated with the most recent state transition (e.g., the reason why the cluster entered the TERMINATED state).
start_time INT64 Time (in epoch milliseconds) when the cluster creation request was received (when the cluster entered the PENDING state).
terminated_time INT64 Time (in epoch milliseconds) when the cluster was terminated, if applicable.
last_state_loss_time INT64 Time when the cluster driver last lost its state (due to a restart or driver failure).
last_activity_time INT64 Time (in epoch milliseconds) when the cluster was last active. A cluster is active if there is at least one command that has not finished on the cluster. This field is available after the cluster has reached the RUNNING state. Updates to this field are made as best-effort attempts. Certain versions of Spark do not support reporting of cluster activity. Refer to Automatic termination for details.
cluster_memory_mb INT64 Total amount of cluster memory, in megabytes.
cluster_cores FLOAT Number of CPU cores available for this cluster. This can be fractional, e.g. 7.5 cores, since certain node types are configured to share cores between Spark nodes on the same instance.
default_tags ClusterTag An object containing a set of tags that are added by Azure Databricks regardless of any custom_tags, including:

* Vendor: Databricks
* Creator:
* ClusterName:
* ClusterId:
* Name: On job clusters:

* RunName:
* JobId:
cluster_log_status LogSyncStatus Cluster log delivery status.
termination_reason TerminationReason Information about why the cluster was terminated. This field appears only when the cluster is in the TERMINATING or TERMINATED state.

Pin

Note

You must be an Azure Databricks administrator to invoke this API.

Endpoint HTTP Method
2.0/clusters/pin POST

Ensure that an all-purpose cluster configuration is retained even after a cluster has been terminated for more than 30 days. Pinning ensures that the cluster is always returned by the List API. Pinning a cluster that is already pinned has no effect.

An example request:

{
  "cluster_id": "1202-211320-brick1"
}

Request structure

Field Name Type Description
cluster_id STRING The cluster to pin. This field is required.

Unpin

Note

You must be an Azure Databricks administrator to invoke this API.

Endpoint HTTP Method
2.0/clusters/unpin POST

Allows the cluster to eventually be removed from the list returned by the List API. Unpinning a cluster that is not pinned has no effect.

An example request:

{
  "cluster_id": "1202-211320-brick1"
}

Request structure

Field Name Type Description
cluster_id STRING The cluster to unpin. This field is required.

List

Endpoint HTTP Method
2.0/clusters/list GET

Return information about all pinned clusters, active clusters, up to 70 of the most recently terminated all-purpose clusters in the past 30 days, and up to 30 of the most recently terminated job clusters in the past 30 days. For example, if there is 1 pinned cluster, 4 active clusters, 45 terminated all-purpose clusters in the past 30 days, and 50 terminated job clusters in the past 30 days, then this API returns the 1 pinned cluster, 4 active clusters, all 45 terminated all-purpose clusters, and the 30 most recently terminated job clusters.

Response structure

Field Name Type Description
clusters An array of ClusterInfo A list of clusters.

List node types

Endpoint HTTP Method
2.0/clusters/list-node-types GET

Return a list of supported Spark node types. These node types can be used to launch a cluster.

Response structure

Field Name Type Description
node_types An array of NodeType The list of available Spark node types.

Runtime versions

Endpoint HTTP Method
2.0/clusters/spark-versions GET

Return the list of available runtime versions. These versions can be used to launch a cluster.

Response structure

Field Name Type Description
versions An array of SparkVersion All the available runtime versions.

Events

Endpoint HTTP Method
2.0/clusters/events POST

Retrieve a list of events about the activity of a cluster. You can retrieve events from active clusters (running, pending, or reconfiguring) and terminated clusters within 30 days of their last termination. This API is paginated. If there are more events to read, the response includes all the parameters necessary to request the next page of events.

An example request:

{
  "cluster_id": "1202-211320-brick1"
}

An example response:

{
  "events": [{
    "cluster_id": "1202-211320-brick1",
    "timestamp": 1534371918659,
    "type": "TERMINATING",
    "details": {
      "reason": {
        "code": "INACTIVITY",
        "parameters": {
          "inactivity_duration_min": "120"
        }
      }
    }
  }, {
    "cluster_id": "1202-211320-brick1",
    "timestamp": 1534358289590,
    "type": "RUNNING",
    "details": {
      "current_num_workers": 2,
      "target_num_workers": 2
    }
  }, {
    "cluster_id": "1202-211320-brick1",
    "timestamp": 1533225298406,
    "type": "RESTARTING",
    "details": {
      "user": "admin"
    }
  }],
  "next_page": {
    "cluster_id": "0802-034608-aloe926",
    "end_time": 1534371918659,
    "offset": 50
  },
  "total_count": 55
}

Example request to retrieve the next page of events:

{
  "cluster_id": "1202-211320",
  "start_time": 1534371918659
}

Request structure

Retrieve events pertaining to a specific cluster.

Field Name Type Description
cluster_id STRING The ID of the cluster to retrieve events about. This field is required.
start_time INT64 The start time in epoch milliseconds. If empty, returns events starting from the beginning of time.
end_time INT64 The end time in epoch milliseconds. If empty, returns events up to the current time.
order ListOrder The order to list events in; either ASC or DESC. Defaults to DESC.
event_types An array of ClusterEventType An optional set of event types to filter on. If empty, all event types are returned.
offset INT64 The offset in the result set. Defaults to 0 (no offset). When an offset is specified and the results are requested in descending order, the end_time field is required.
limit INT64 The maximum number of events to include in a page of events. Defaults to 50, and maximum allowed value is 500.

Response structure

Field Name Type Description
events An array of ClusterEvent This list of matching events.
next_page Request structure The parameters required to retrieve the next page of events. Omitted if there are no more events to read.
total_count INT64 The total number of events filtered by the start_time, end_time, and event_types.

Data structures

In this section:

AutoScale

Range defining the min and max number of cluster workers.

Field Name Type Description
min_workers INT32 The minimum number of workers to which the cluster can scale down when underutilized. It is also the initial number of workers the cluster will have after creation.
max_workers INT32 The maximum number of workers to which the cluster can scale up when overloaded. max_workers must be strictly greater than min_workers.

ClusterInfo

Metadata about a cluster.

Field Name Type Description
num_workers OR autoscale INT32 OR AutoScale If num_workers, number of worker nodes that this cluster should have. A cluster has one Spark driver and num_workers executors for a total of num_workers + 1 Spark nodes.

Note: When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field will immediately be updated to reflect the target size of 10 workers, whereas the workers listed in executors will gradually increase from 5 to 10 as the new nodes are provisioned.

If autoscale, parameters needed in order to automatically scale clusters up and down based on load.
cluster_id STRING Canonical identifier for the cluster. This ID is retained during cluster restarts and resizes, while each new cluster has a globally unique ID.
creator_user_name STRING Creator user name. The field won’t be included in the response if the user has already been deleted.
driver SparkNode Node on which the Spark driver resides. The driver node contains the Spark master and the Databricks application that manages the per-notebook Spark REPLs.
executors An array of SparkNode Nodes on which the Spark executors reside.
spark_context_id INT64 A canonical SparkContext identifier. This value does change when the Spark driver restarts. The pair (cluster_id, spark_context_id) is a globally unique identifier over all Spark contexts.
jdbc_port INT32 Port on which Spark JDBC server is listening in the driver node. No service will be listening on on this port in executor nodes.
cluster_name STRING Cluster name requested by the user. This doesn’t have to be unique. If not specified at creation, the cluster name will be an empty string.
spark_version STRING The runtime version of the cluster. You can retrieve a list of available runtime versions by using the Runtime versions API call.
spark_conf SparkConfPair An object containing a set of optional, user-specified Spark configuration key-value pairs. You can also pass in a string of extra JVM options to the driver and the executors via
spark.driver.extraJavaOptions and spark.executor.extraJavaOptions respectively.

Example Spark confs:
{"spark.speculation": true, "spark.streaming.ui.retainedBatches": 5} or
{"spark.driver.extraJavaOptions": "-verbose:gc -XX:+PrintGCDetails"}
node_type_id STRING This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute intensive workloads. A list of available node types can be retrieved by using the List node types API call.
driver_node_type_id STRING The node type of the Spark driver. This field is optional; if unset, the driver node type will be set as the same value as node_type_id defined above.
cluster_log_conf ClusterLogConf The configuration for delivering Spark logs to a long-term storage destination. Only one destination can be specified for one cluster. If the conf is given, the logs will be delivered to the destination every
5 mins. The destination of driver logs is <destination>/<cluster-ID>/driver, while the destination of executor logs is <destination>/<cluster-ID>/executor.
init_scripts An array of InitScriptInfo The configuration for storing init scripts. Any number of destinations can be specified. The scripts are executed sequentially in the order provided. If cluster_log_conf is specified, init script logs are sent to
<destination>/<cluster-ID>/init_scripts.
docker_image DockerImage Docker image for a custom container.
spark_env_vars SparkEnvPair An object containing a set of optional, user-specified environment variable key-value pairs. Key-value pairs of the form (X,Y) are exported as is (i.e.,
export X='Y') while launching the driver and workers.

To specify an additional set of SPARK_DAEMON_JAVA_OPTS, we recommend appending them to $SPARK_DAEMON_JAVA_OPTS as shown in the following example. This ensures that all default databricks managed environmental variables are included as well.

Example Spark environment variables:
{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"} or
{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}
autotermination_minutes INT32 Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this cluster will not be automatically terminated. If specified, the threshold must be between 10 and 10000 minutes. You can also set this value to 0 to explicitly disable automatic termination.
enable_elastic_disk BOOL Autoscaling Local Storage: when enabled, this cluster will dynamically acquire additional disk space when its Spark workers are running low on disk space. See Autoscaling local storage for details.
instance_pool_id STRING The optional ID of the instance pool to which the cluster belongs. Refer to Pools for details.
state ClusterState State of the cluster.
state_message STRING A message associated with the most recent state transition (e.g., the reason why the cluster entered a TERMINATED state).
start_time INT64 Time (in epoch milliseconds) when the cluster creation request was received (when the cluster entered a PENDING state).
terminated_time INT64 Time (in epoch milliseconds) when the cluster was terminated, if applicable.
last_state_loss_time INT64 Time when the cluster driver last lost its state (due to a restart or driver failure).
last_activity_time INT64 Time (in epoch milliseconds) when the cluster was last active. A cluster is active if there is at least one command that has not finished on the cluster. This field is available after the cluster has reached a RUNNING state. Updates to this field are made as best-effort attempts. Certain versions of Spark do not support reporting of cluster activity. Refer to Automatic termination for details.
cluster_memory_mb INT64 Total amount of cluster memory, in megabytes.
cluster_cores FLOAT Number of CPU cores available for this cluster. This can be fractional, e.g. 7.5 cores, since certain node types are configured to share cores between Spark nodes on the same instance.
default_tags ClusterTag An object containing a set of tags that are added by Azure Databricks regardless of any custom_tags, including:

* Vendor: Databricks
* Creator:
* ClusterName:
* ClusterId:
* Name: On job clusters:

* RunName:
* JobId:
cluster_log_status LogSyncStatus Cluster log delivery status.
termination_reason TerminationReason Information about why the cluster was terminated. This field only appears when the cluster is in a TERMINATING or TERMINATED state.

ClusterEvent

Cluster event information.

Field Name Type Description
cluster_id STRING Canonical identifier for the cluster. This field is required.
timestamp INT64 The timestamp when the event occurred, stored as the number of milliseconds since the unix epoch. Assigned by the Timeline service.
type ClusterEventType The event type. This field is required.
details EventDetails The event details. This field is required.

ClusterEventType

Type of a cluster event.

Event Type Description
CREATING Indicates that the cluster is being created.
DID_NOT_EXPAND_DISK Indicates that a disk is low on space, but adding disks would put it over the max capacity.
EXPANDED_DISK Indicates that a disk was low on space and the disks were expanded.
FAILED_TO_EXPAND_DISK Indicates that a disk was low on space and disk space could not be expanded.
INIT_SCRIPTS_STARTING Indicates that the cluster scoped init script has started.
INIT_SCRIPTS_FINISHED Indicates that the cluster scoped init script has finished.
STARTING Indicates that the cluster is being started.
RESTARTING Indicates that the cluster is being started.
TERMINATING Indicates that the cluster is being terminated.
EDITED Indicates that the cluster has been edited.
RUNNING Indicates the cluster has finished being created. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.
RESIZING Indicates a change in the target size of the cluster (upsize or downsize).
UPSIZE_COMPLETED Indicates that nodes finished being added to the cluster. Includes the number of nodes in the cluster and a failure reason if some nodes could not be acquired.
NODES_LOST Indicates that some nodes were lost from the cluster.
DRIVER_HEALTHY Indicates that the driver is healthy and the cluster is ready for use.
DRIVER_UNAVAILABLE Indicates that the driver is unavailable.
SPARK_EXCEPTION Indicates that a Spark exception was thrown from the driver.
DRIVER_NOT_RESPONDING Indicates that the driver is up but is not responsive, likely due to GC.
DBFS_DOWN Indicates that the driver is up but DBFS is down.
METASTORE_DOWN Indicates that the driver is up but the metastore is down.
NODE_BLACKLISTED Indicates that a node is not allowed by Spark.
PINNED Indicates that the cluster was pinned.
UNPINNED Indicates that the cluster was unpinned.

EventDetails

Details about a cluster event.

Field Name Type Description
current_num_workers INT32 The number of nodes in the cluster.
target_num_workers INT32 The targeted number of nodes in the cluster.
previous_attributes ClusterAttributes The cluster attributes before a cluster was edited.
attributes ClusterAttributes * For created clusters, the attributes of the cluster.
* For edited clusters, the new attributes of the cluster.
previous_cluster_size ClusterSize The size of the cluster before an edit or resize.
cluster_size ClusterSize The cluster size that was set in the cluster creation or edit.
cause ResizeCause The cause of a change in target size.
reason TerminationReason A termination reason:

* On a TERMINATED event, the reason for the termination.
* On a RESIZE_COMPLETE event, indicates the reason that we failed to acquire some nodes.
user STRING The user that caused the event to occur. (Empty if it was done by Azure Databricks.)

ClusterAttributes

Common set of attributes set during cluster creation. These attributes cannot be changed over the lifetime of a cluster.

Field Name Type Description
cluster_name STRING Cluster name requested by the user. This doesn’t have to be unique. If not specified at creation, the cluster name will be an empty string.
spark_version STRING The runtime version of the cluster, e.g. “5.0.x-scala2.11”. You can retrieve a list of available runtime versions by using the Runtime versions API call.
spark_conf SparkConfPair An object containing a set of optional, user-specified Spark configuration key-value pairs. You can also pass in a string of extra JVM options to the driver and the executors via
spark.driver.extraJavaOptions and spark.executor.extraJavaOptions respectively.

Example Spark confs:
{"spark.speculation": true, "spark.streaming.ui.retainedBatches": 5} or
{"spark.driver.extraJavaOptions": "-verbose:gc -XX:+PrintGCDetails"}
node_type_id STRING This field encodes, through a single value, the resources available to each of the Spark nodes in this cluster. For example, the Spark nodes can be provisioned and optimized for memory or compute intensive workloads A list of available node types can be retrieved by using the List node types API call.
driver_node_type_id STRING The node type of the Spark driver. This field is optional; if unset, the driver node type will be set as the same value as node_type_id defined above.
ssh_public_keys An array of STRING SSH public key contents that will be added to each Spark node in this cluster. The corresponding private keys can be used to login with the user name ubuntu on port 2200. Up to 10 keys can be specified.
custom_tags ClusterTag An object containing a set of tags for cluster resources. Databricks tags all cluster resources with these tags in addition to default_tags.

Note:

* Tags are not supported on legacy node types such as compute-optimized and memory-optimized
* Databricks allows at most 45 custom tags
cluster_log_conf ClusterLogConf The configuration for delivering Spark logs to a long-term storage destination. Only one destination can be specified for one cluster. If the conf is given, the logs will be delivered to the destination every
5 mins. The destination of driver logs is <destination>/<cluster-ID>/driver, while the destination of executor logs is <destination>/<cluster-ID>/executor.
init_scripts An array of InitScriptInfo The configuration for storing init scripts. Any number of destinations can be specified. The scripts are executed sequentially in the order provided. If cluster_log_conf is specified, init script logs are sent to
<destination>/<cluster-ID>/init_scripts.
docker_image DockerImage Docker image for a custom container.
spark_env_vars SparkEnvPair An object containing a set of optional, user-specified environment variable key-value pairs. Key-value pairs of the form (X,Y) are exported as is (i.e.,
export X='Y') while launching the driver and workers.

In order to specify an additional set of SPARK_DAEMON_JAVA_OPTS, we recommend appending them to $SPARK_DAEMON_JAVA_OPTS as shown in the following example. This ensures that all default databricks managed environmental variables are included as well.

Example Spark environment variables:
{"SPARK_WORKER_MEMORY": "28000m", "SPARK_LOCAL_DIRS": "/local_disk0"} or
{"SPARK_DAEMON_JAVA_OPTS": "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"}
autotermination_minutes INT32 Automatically terminates the cluster after it is inactive for this time in minutes. If not set, this cluster will not be automatically terminated. If specified, the threshold must be between 10 and 10000 minutes. You can also set this value to 0 to explicitly disable automatic termination.
enable_elastic_disk BOOL Autoscaling Local Storage: when enabled, this cluster will dynamically acquire additional disk space when its Spark workers are running low on disk space. See Autoscaling local storage for details.
instance_pool_id STRING The optional ID of the instance pool to which the cluster belongs. Refer to Pools for details.
cluster_source ClusterSource Determines whether the cluster was created by a user through the UI, created by the Databricks Jobs scheduler, or through an API request.
policy_id STRING A cluster policy ID.

ClusterSize

Cluster size specification.

Field Name Type Description
num_workers OR autoscale INT32 OR AutoScale If num_workers, number of worker nodes that this cluster should have. A cluster has one Spark driver and num_workers executors for a total of num_workers + 1 Spark nodes.

When reading the properties of a cluster, this field reflects the desired number of workers rather than the actual number of workers. For instance, if a cluster is resized from 5 to 10 workers, this field is updated to reflect the target size of 10 workers, whereas the workers listed in executors gradually increase from 5 to 10 as the new nodes are provisioned.

If autoscale, parameters needed in order to automatically scale clusters up and down based on load.

ListOrder

Generic ordering enum for list-based queries.

Order Description
DESC Descending order
ASC Ascending order

ResizeCause

Reason why a cluster was resized.

Cause Description
AUTOSCALE Automatically resized based on load.
USER_REQUEST User requested a new size.
AUTORECOVERY Autorecovery monitor resized the cluster after it lost a node.

ClusterLogConf

Path to cluster log.

Field Name Type Description
dbfs DbfsStorageInfo DBFS location of cluster log. destination must be provided. For example,
{ "dbfs" : { "destination" : "dbfs:/home/cluster_log" } }

InitScriptInfo

Path to an init script.

Field Name Type Description
dbfs DbfsStorageInfo DBFS location of init script. destination must be provided. For example,
{ "dbfs" : { "destination" : "dbfs:/home/init_script" } }

ClusterTag

Cluster tag definition.

Type Description
STRING The key of the tag. The key must:

* Be between 1 and 512 characters long
* Not contain any of the characters <>%*&+?\\/
* Not begin with azure, microsoft, or windows
STRING The value of the tag. The value length must be less than or equal to 256 UTF-8 characters.

DbfsStorageInfo

DBFS storage information.

Field Name Type Description
destination STRING DBFS destination, e.g. dbfs:/my/path

DockerImage

Docker image connection information.

Field Type Description
url string URL for the Docker image.
basic_auth DockerBasicAuth Basic authentication information for Docker repository.

DockerBasicAuth

Docker repository basic authentication information.

Field Description
username User name for the Docker repository.
password Password for the Docker repository.

LogSyncStatus

Log delivery status.

Field Name Type Description
last_attempted INT64 The timestamp of last attempt. If the last attempt fails, last_exception contains the exception in the last attempt.
last_exception STRING The exception thrown in the last attempt, it would be null (omitted in the response) if there is no exception in last attempted.

NodeType

Description of a Spark node type including both the dimensions of the node and the instance type on which it will be hosted.

Field Name Type Description
node_type_id STRING Unique identifier for this node type. This field is required.
memory_mb INT32 Memory (in MB) available for this node type. This field is required.
num_cores FLOAT Number of CPU cores available for this node type. This can be fractional, e.g., 2.5 cores, if the the number of cores on a machine instance is not divisible by the number of Spark nodes on that machine. This field is required.
description STRING A string description associated with this node type. This field is required.
instance_type_id STRING An identifier for the type of hardware that this node runs on. This field is required.
is_deprecated BOOL Whether the node type is deprecated. Non-deprecated node types offer greater performance.
node_info ClusterCloudProviderNodeInfo Node type info reported by the cloud provider.

ClusterCloudProviderNodeInfo

Information about an instance supplied by a cloud provider.

Field Name Type Description
status ClusterCloudProviderNodeStatus Status as reported by the cloud provider.
available_core_quota INT32 Available CPU core quota.
total_core_quota INT32 Total CPU core quota.

ClusterCloudProviderNodeStatus

Status of an instance supplied by a cloud provider.

Status Description
NotEnabledOnSubscription Node type not available for subscription.
NotAvailableInRegion Node type not available in region.

ParameterPair

Parameter that provides additional information about why a cluster was terminated.

Type Description
TerminationParameter Type of termination information.
STRING The termination information.

SparkConfPair

Spark configuration key-value pairs.

Type Description
STRING A configuration property name.
STRING The configuration property value.

SparkEnvPair

Spark environment variable key-value pairs.

Important

When specifying environment variables in a job cluster, the fields in this data structure accept only Latin characters (ASCII character set). Using non-ASCII characters will return an error. Examples of invalid, non-ASCII characters are Chinese, Japanese kanjis, and emojis.

Type Description
STRING An environment variable name.
STRING The environment variable value.

SparkNode

Spark driver or executor configuration.

Field Name Type Description
private_ip STRING Private IP address (typically a 10.x.x.x address) of the Spark node. This is different from the private IP address of the host instance.
public_dns STRING Public DNS address of this node. This address can be used to access the Spark JDBC server on the driver node.
node_id STRING Globally unique identifier for this node.
instance_id STRING Globally unique identifier for the host instance from the cloud provider.
start_timestamp INT64 The timestamp (in millisecond) when the Spark node is launched.
host_private_ip STRING The private IP address of the host instance.

SparkVersion

Databricks Runtime version of the cluster.

Field Name Type Description
key STRING Databricks Runtime version key, for example 6.0.x-scala2.11. The value that should be provided as the spark_version when creating a new cluster. The exact runtime version may change over time for a “wildcard” version (that is, 6.0.x-scala2.11 is a “wildcard” version) with minor bug fixes.
name STRING A descriptive name for the runtime version, for example “Databricks Runtime 6.0”.

TerminationReason

Reason why a cluster was terminated.

Field Name Type Description
code TerminationCode Status code indicating why a cluster was terminated.
type TerminationType Reason indicating why a cluster was terminated.
parameters ParameterPair Object containing a set of parameters that provide information about why a cluster was terminated.

PoolClusterTerminationCode

Status code indicating why the cluster was terminated due to a pool failure.

Code Description
INSTANCE_POOL_MAX_CAPACITY_FAILURE The pool max capacity has been reached.
INSTANCE_POOL_NOT_FOUND_FAILURE The pool specified by the cluster is no longer active or doesn’t exist.

ClusterSource

Service that created the cluster.

Service Description
UI Cluster created through the UI.
JOB Cluster created by the Databricks job scheduler.
API Cluster created through an API call.

ClusterState

State of a cluster. The allowable state transitions are as follows:

  • PENDING -> RUNNING
  • PENDING -> TERMINATING
  • RUNNING -> RESIZING
  • RUNNING -> RESTARTING
  • RUNNING -> TERMINATING
  • RESTARTING -> RUNNING
  • RESTARTING -> TERMINATING
  • RESIZING -> RUNNING
  • RESIZING -> TERMINATING
  • TERMINATING -> TERMINATED
State Description
PENDING Indicates that a cluster is in the process of being created.
RUNNING Indicates that a cluster has been started and is ready for use.
RESTARTING Indicates that a cluster is in the process of restarting.
RESIZING Indicates that a cluster is in the process of adding or removing nodes.
TERMINATING Indicates that a cluster is in the process of being destroyed.
TERMINATED Indicates that a cluster has been successfully destroyed.
ERROR This state is no longer used. It was used to indicate a cluster that failed to be created.
TERMINATING and TERMINATED are used instead.
UNKNOWN Indicates that a cluster is in an unknown state. A cluster should never be in this state.

TerminationCode

Status code indicating why the cluster was terminated.

Code Description
USER_REQUEST A user terminated the cluster directly. Parameters should include a username field that indicates the specific user who terminated the cluster.
JOB_FINISHED The cluster was launched by a job, and terminated when the job completed.
INACTIVITY The cluster was terminated since it was idle.
CLOUD_PROVIDER_SHUTDOWN The instance that hosted the Spark driver was terminated by the cloud provider.
COMMUNICATION_LOST Azure Databricks lost connection to services on the driver instance. For example, this can happen when problems arise in cloud networking infrastructure, or when the instance itself becomes unhealthy.
CLOUD_PROVIDER_LAUNCH_FAILURE Azure Databricks experienced a cloud provider failure when requesting instances to launch clusters.
SPARK_STARTUP_FAILURE The cluster failed to initialize. Possible reasons may include failure to create the environment for Spark or issues launching the Spark master and worker processes.
INVALID_ARGUMENT Cannot launch the cluster because the user specified an invalid argument. For example, the user might specify an invalid runtime version for the cluster.
UNEXPECTED_LAUNCH_FAILURE While launching this cluster, Azure Databricks failed to complete critical setup steps, terminating the cluster.
INTERNAL_ERROR Azure Databricks encountered an unexpected error that forced the running cluster to be terminated. Contact Azure Databricks support for additional details.
SPARK_ERROR The Spark driver failed to start. Possible reasons may include incompatible libraries and initialization scripts that corrupted the Spark container.
METASTORE_COMPONENT_UNHEALTHY The cluster failed to start because the external metastore could not be reached. Refer to Troubleshooting.
DBFS_COMPONENT_UNHEALTHY The cluster failed to start because Databricks File System (DBFS) could not be reached.
AZURE_RESOURCE_PROVIDER_THROTTLING Azure Databricks reached the Azure Resource Provider request limit. Specifically, the API request rate to the specific resource type (compute, network, etc.) can’t exceed the limit. Retry might help to resolve the issue. For further information, seehttps://docs.microsoft.com/azure/virtual-machines/troubleshooting/troubleshooting-throttling-errors.
AZURE_RESOURCE_MANAGER_THROTTLING Azure Databricks reached the Azure Resource Manager request limit which will prevent the Azure SDK from issuing any read or write request to the Azure Resource Manager. The request limit is applied to each subscription every hour. Retry after an hour or changing to a smaller cluster size might help to resolve the issue. For further information, seehttps://docs.microsoft.com/azure/azure-resource-manager/resource-manager-request-limits.
NETWORK_CONFIGURATION_FAILURE The cluster was terminated due to an error in the network configuration. For example, a workspace with VNet injection had incorrect DNS settings that blocked access to worker artifacts.
DRIVER_UNREACHABLE Azure Databricks was not able to access the Spark driver, because it was not reachable.
DRIVER_UNRESPONSIVE Azure Databricks was not able to access the Spark driver, because it was unresponsive.
INSTANCE_UNREACHABLE Azure Databricks was not able to access instances in order to start the cluster. This can be a transient networking issue. If the problem persists, this usually indicates a networking environment misconfiguration.
CONTAINER_LAUNCH_FAILURE Azure Databricks was unable to launch containers on worker nodes for the cluster. Have your admin check your network configuration.
INSTANCE_POOL_CLUSTER_FAILURE Pool backed cluster specific failure. Refer to Pools for details.
REQUEST_REJECTED Azure Databricks cannot handle the request at this moment. Try again later and contact Azure Databricks if the problem persists.
INIT_SCRIPT_FAILURE Azure Databricks cannot load and run a cluster-scoped init script on one of the cluster’s nodes, or the init script terminates with a non-zero exit code. Refer to Init script logs.
TRIAL_EXPIRED The Azure Databricks trial subscription expired.

TerminationType

Reason why the cluster was terminated.

Type Description
SUCCESS Termination succeeded.
CLIENT_ERROR Non-retriable. Client must fix parameters before reattempting the cluster creation.
SERVICE_FAULT Azure Databricks service issue. Client can retry.
CLOUD_FAILURE Cloud provider infrastructure issue. Client can retry after the underlying issue is resolved.

TerminationParameter

Key that provides additional information about why a cluster was terminated.

Key Description
username The username of the user who terminated the cluster.
databricks_error_message Additional context that may explain the reason for cluster termination.
inactivity_duration_min An idle cluster was shut down after being inactive for this duration.
instance_id The ID of the instance that was hosting the Spark driver.
azure_error_code The Azure provided error code describing why cluster nodes could not be provisioned. For reference, see: https://docs.microsoft.com/azure/virtual-machines/windows/error-messages.
azure_error_message Human-readable context of various failures from Azure. This field is unstructured, and its exact format is subject to change.
instance_pool_id The ID of the instance pool the cluster is using.
instance_pool_error_code The error code for cluster failures specific to a pool.