# Get instance pool information

Launch stage: GA

`GET /api/2.0/instance-pools/get`

Retrieve the information for an instance pool based on its identifier.

API scopes: instance-pools

## Query parameters

- `instance_pool_id` (string, required)
  The canonical unique identifier for the instance pool.
  Example: `1234-567890-fetch12-pool-A3BcdEFg`

## Returns

- `stats` (object, optional)
  Usage statistics about the instance pool.
  - `used_count` (int32, optional)
    Number of active instances in the pool that are part of a cluster.
  - `idle_count` (int32, optional)
    Number of active instances in the pool that are NOT part of a cluster.
  - `pending_used_count` (int32, optional)
    Number of pending instances in the pool that are part of a cluster.
  - `pending_idle_count` (int32, optional)
    Number of pending instances in the pool that are NOT part of a cluster.
- `status` (object, optional)
  Status of failed pending instances in the pool.
  - `pending_instance_errors` (array of object, optional)
    List of error messages for the failed pending instances.
     The pending_instance_errors follows FIFO with maximum length of the min_idle of the pool.
     The pending_instance_errors is emptied once the number of exiting available instances reaches
     the min_idle of the pool.
    - `instance_id` (string, optional)
    - `message` (string, optional)
- `instance_pool_id` (string, optional)
  Canonical unique identifier for the pool.
- `default_tags` (object, optional)
  Tags that are added by Databricks regardless of any ``custom_tags``, including:
  
     - Vendor: Databricks
  
     - InstancePoolCreator: <user_id_of_creator>
  
     - InstancePoolName: <name_of_pool>
  
     - InstancePoolId: <id_of_pool>
- `state` (string, optional)
  Current state of the instance pool.
  Possible values:
  - `ACTIVE`
  - `STOPPED`
  - `DELETED`
- `instance_pool_name` (string, optional)
  Pool name requested by the user. Pool name must be unique. Length must be between 1 and 100
   characters.
  Example: `my-pool`
- `min_idle_instances` (int32, optional)
  Minimum number of idle instances to keep in the instance pool
  Example: `5`
- `max_capacity` (int32, optional)
  Maximum number of outstanding instances to keep in the pool, including both instances used by
   clusters and idle instances. Clusters that require further instance provisioning will fail during
   upsize requests.
  Example: `200`
- `aws_attributes` (object, optional)
  Attributes related to instance pools running on Amazon Web Services.
   If not specified at pool creation, a set of default values will be used.
  - `availability` (string, optional)
    Availability type used for the instances in the pool. Supports on-demand, spot, and
     spot-with-fallback (the pool acquires spot instances first, and falls back to on-demand
     instances when spot capacity is unavailable).
    
     You can change this value on an existing pool. New clusters use the updated availability, and
     existing clusters keep the availability they launched with.
    Possible values:
    - `SPOT`
    - `ON_DEMAND`
    - `SPOT_WITH_FALLBACK`
  - `zone_id` (string, optional)
    Identifier for the availability zone/datacenter in which the cluster resides.
     This string will be of a form like "us-west-2a". The provided availability
     zone must be in the same region as the Databricks deployment. For example, "us-west-2a"
     is not a valid zone id if the Databricks deployment resides in the "us-east-1" region.
     This is an optional field at cluster creation, and if not specified, a default zone will be used.
     The list of available zones as well as the default value can be found by using the
     `List Zones` method.
    
     Set this field to "auto" to enable Auto-AZ, in which case Databricks selects the availability
     zone for each cluster independently when the cluster launches, and retries another zone if the
     cluster can't be fulfilled because of insufficient capacity or quota. All nodes in a cluster
     land in the same zone, and different clusters backed by the pool can run in different zones.
    
     You can change the zone on an existing pool. New clusters use the updated zone, and existing
     clusters keep the zone they launched with.
  - `spot_bid_price_percent` (int32, optional)
    Calculates the bid price for AWS spot instances, as a percentage of the corresponding instance type's
     on-demand price.
     For example, if this field is set to 50, and the cluster needs a new `r3.xlarge` spot
     instance, then the bid price is half of the price of
     on-demand `r3.xlarge` instances. Similarly, if this field is set to 200, the bid price is twice
     the price of on-demand `r3.xlarge` instances. If not specified, the default value is 100.
     When spot instances are requested for this cluster, only spot instances whose bid price
     percentage matches this field will be considered.
     Note that, for safety, we enforce this field to be no more than 10000.
    
     You can change this value on an existing pool. New clusters use the updated bid price, and
     existing clusters keep the bid price they launched with.
    Default: `100`
  - `instance_profile_arn` (string, optional, Beta)
    All AWS instances belonging to the instance pool will have this instance profile. If omitted, instances
     will initially be launched with the workspace's default instance profile. If defined, clusters that use the
     pool will inherit the instance profile, and must not specify their own instance profile on cluster creation or
     update. If the pool does not specify an instance profile, clusters using the pool may specify any instance profile.
     The instance profile must have previously been added to the Databricks environment by an account administrator.
    
     This feature may only be available to certain customer plans.
- `node_type_id` (string, optional)
  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 [clusters/listNodeTypes](https://docs.databricks.com/api/workspace/clusters/listnodetypes) API call.
- `custom_tags` (object, optional)
  Additional tags for pool resources. Databricks will tag all pool resources (e.g., AWS
   instances and EBS volumes) with these tags in addition to `default_tags`. Notes:
  
   - Currently, Databricks allows at most 45 custom tags
- `idle_instance_autotermination_minutes` (int32, optional)
  Automatically terminates the extra instances in the pool cache after they are inactive for this
   time in minutes if min_idle_instances requirement is already met. If not set, the extra pool
   instances will be automatically terminated after a default timeout. If specified, the
   threshold must be between 0 and 10000 minutes.
   Users can also set this value to 0 to instantly remove idle instances from the cache if
   min cache size could still hold.
  Example: `30`
- `enable_elastic_disk` (boolean, optional)
  Autoscaling Local Storage: when enabled, this instances in this pool will dynamically acquire
   additional disk space when its Spark workers are running low on disk space. In AWS, this
   feature requires specific AWS permissions to function correctly - refer to the User Guide for
   more details.
- `disk_spec` (object, optional)
  Defines the specification of the disks that will be attached to all spark containers.
  - `disk_type` (object, optional)
    The type of disks that will be launched with this cluster.
    - `ebs_volume_type` (string, optional)
      Possible values:
      - `GENERAL_PURPOSE_SSD`
      - `THROUGHPUT_OPTIMIZED_HDD`
    - `azure_disk_volume_type` (string, optional)
      Possible values:
      - `PREMIUM_LRS`
      - `STANDARD_LRS`
  - `disk_count` (int32, optional)
    The number of disks launched for each instance:
     - This feature is only enabled for supported node types.
     - Users can choose up to the limit of the disks supported by the node type.
     - For node types with no OS disk, at least one disk must be specified;
     otherwise, cluster creation will fail.
    
     If disks are attached, Databricks will configure Spark to use only the disks for
     scratch storage, because heterogenously sized scratch devices can lead to inefficient disk
     utilization. If no disks are attached, Databricks will configure Spark to use
     instance store disks.
    
     Note: If disks are specified, then the Spark configuration
     `spark.local.dir` will be overridden.
    
     Disks will be mounted at:
     - For AWS: `/ebs0`, `/ebs1`, and etc.
     - For Azure: `/remote_volume0`, `/remote_volume1`, and etc.
    Default: `0`
  - `disk_size` (int32, optional)
    The size of each disk (in GiB) launched for each instance.
     Values must fall into the supported range for a particular instance type.
    
     For AWS:
     - General Purpose SSD: 100 - 4096 GiB
     - Throughput Optimized HDD: 500 - 4096 GiB
    
     For Azure:
     - Premium LRS (SSD): 1 - 1023 GiB
     - Standard LRS (HDD): 1- 1023 GiB
  - `disk_iops` (int32, optional)
  - `disk_throughput` (int32, optional)
- `preloaded_docker_images` (array of object, optional)
  Custom Docker Image BYOC
  - `url` (string, optional)
    URL of the docker image.
  - `basic_auth` (object, optional)
    Basic auth with username and password
    - `username` (string, optional)
      Name of the user
    - `password` (string, optional)
      Password of the user
- `preloaded_spark_versions` (array of string, optional)
  A list containing at most one preloaded Spark image version for the pool. Pool-backed clusters started
   with the preloaded Spark version will start faster. A list of available Spark versions
   can be retrieved by using the [clusters/sparkVersions](https://docs.databricks.com/api/workspace/clusters/sparkversions) API call.
- `azure_attributes` (object, optional)
  Attributes related to instance pools running on Azure.
   If not specified at pool creation, a set of default values will be used.
  - `availability` (string, optional)
    Availability type used for the instances in the pool. Supports on-demand, spot, and
     spot-with-fallback (the pool acquires spot instances first, and falls back to on-demand
     instances when spot capacity is unavailable).
    
     You can change this value on an existing pool. New clusters use the updated availability, and
     existing clusters keep the availability they launched with.
    Possible values:
    - `SPOT_AZURE`
    - `ON_DEMAND_AZURE`
    - `SPOT_WITH_FALLBACK_AZURE`
    Default: `ON_DEMAND_AZURE`
  - `spot_bid_max_price` (double, optional)
    With variable pricing, you have option to set a max price, in US dollars (USD)
     For example, the value 2 would be a max price of $2.00 USD per hour.
     If you set the max price to be -1, the VM won't be evicted based on price.
     The price for the VM will be the current price for spot or the price for a standard VM,
     which ever is less, as long as there is capacity and quota available.
    
     You can change this value on an existing pool. New clusters use the updated max price, and
     existing clusters keep the max price they launched with.
    Default: `-1`
  - `capacity_reservation_group` (string, optional)
    The Azure capacity reservation group resource ID to use for launching VMs in this pool.
     When specified, VMs will be launched using the provided capacity reservation.
    
     NOTE: Omitting this field will clear any existing configured capacity reservation group on the pool.
    
     Capacity reservations can only be specified when the workspace uses injected vnet (i.e. customer defined vnet not
     managed by databricks). Ensure the databricks-login-prod Enterprise Application is granted the following four permissions:
     1. Microsoft.Compute/capacityReservationGroups/read
     2. Microsoft.Compute/capacityReservationGroups/deploy/action
     3. Microsoft.Compute/capacityReservationGroups/capacityReservations/read
     4. Microsoft.Compute/capacityReservationGroups/capacityReservations/deploy/action
    
     Format: `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/capacityReservationGroups/{capacityReservationGroupName}`
- `gcp_attributes` (object, optional)
  Attributes related to instance pools running on Google Cloud Platform.
   If not specified at pool creation, a set of default values will be used.
  - `gcp_availability` (string, optional)
    Availability type for the instances in the pool. One of:
    
     - `ON_DEMAND_GCP`: the pool uses on-demand instances only.
     - `PREEMPTIBLE_GCP`: the pool uses preemptible instances only.
     - `PREEMPTIBLE_WITH_FALLBACK_GCP`: the pool acquires preemptible instances first, and falls
       back to on-demand instances when preemptible capacity is unavailable.
    Possible values:
    - `PREEMPTIBLE_GCP`
    - `ON_DEMAND_GCP`
    - `PREEMPTIBLE_WITH_FALLBACK_GCP`
    Default: `ON_DEMAND_GCP`
  - `local_ssd_count` (int32, optional)
    If provided, each node in the instance pool will have this number of local SSDs attached.
     Each local SSD is 375GB in size. Refer to [GCP documentation](https://cloud.google.com/compute/docs/disks/local-ssd#choose_number_local_ssds)
     for the supported number of local SSDs for each instance type.
  - `zone_id` (string, optional)
    Identifier for the availability zone/datacenter in which the cluster resides.
     This string will be of a form like "us-west1-a". The provided availability
     zone must be in the same region as the Databricks workspace. For example, "us-west1-a"
     is not a valid zone id if the Databricks workspace resides in the "us-east1" region.
     This is an optional field at instance pool creation, and if not specified, a default zone will be used.
    
     This field can be one of the following:
     - "HA" => High availability, spread nodes across availability zones for a Databricks deployment region
     - "auto" => Auto-AZ. Databricks selects the availability zone for each cluster independently when the cluster launches, and retries another zone if the cluster can't be fulfilled because of insufficient capacity or quota. All nodes in a cluster land in the same zone, and different clusters backed by the pool can run in different zones.
     - A GCP availability zone => Pick One of the available zones for (machine type + region) from https://cloud.google.com/compute/docs/regions-zones (e.g. "us-west1-a").
    
     If empty, Databricks picks an availability zone to schedule the cluster on.
    
     You can change the zone on an existing pool. New clusters use the updated zone, and existing
     clusters keep the zone they launched with.
- `node_type_flexibility` (object, optional)
  Flexible node type configuration for the pool.
  - `alternate_node_type_ids` (array of string, optional)
    A list of node type IDs to use as fallbacks when the primary node type is unavailable.
  - `aws_context_id` (string, optional)
    The AWS Context ID for EC2 Fleet.
     When set (non-empty), the value is passed to AWS CreateFleet API to create the EC2 Fleet.
- `remote_disk_throughput` (int32, optional)
  If set, what the configurable throughput (in Mb/s) for the remote disk is. Currently only supported for GCP HYPERDISK_BALANCED types.
- `total_initial_remote_disk_size` (int32, optional)
  If set, what the total initial volume size (in GB) of the remote disks should be. Currently only supported for GCP HYPERDISK_BALANCED types.

## Response

```json
{
  "stats": {
    "used_count": 0,
    "idle_count": 0,
    "pending_used_count": 0,
    "pending_idle_count": 0
  },
  "status": {
    "pending_instance_errors": [
      {}
    ]
  },
  "instance_pool_id": "string",
  "default_tags": {},
  "state": "ACTIVE",
  "instance_pool_name": "my-pool",
  "min_idle_instances": 5,
  "max_capacity": 200,
  "aws_attributes": {
    "availability": "SPOT",
    "zone_id": "string",
    "spot_bid_price_percent": 100,
    "instance_profile_arn": "string"
  },
  "node_type_id": "string",
  "custom_tags": {},
  "idle_instance_autotermination_minutes": 30,
  "enable_elastic_disk": true,
  "disk_spec": {
    "disk_type": {},
    "disk_count": 0,
    "disk_size": 0,
    "disk_iops": 0,
    "disk_throughput": 0
  },
  "preloaded_docker_images": [
    {
      "url": "string",
      "basic_auth": {}
    }
  ],
  "preloaded_spark_versions": [
    "string"
  ],
  "azure_attributes": {
    "availability": "ON_DEMAND_AZURE",
    "spot_bid_max_price": -1,
    "capacity_reservation_group": "string"
  },
  "gcp_attributes": {
    "gcp_availability": "ON_DEMAND_GCP",
    "local_ssd_count": 0,
    "zone_id": "string"
  },
  "node_type_flexibility": {
    "alternate_node_type_ids": [
      "string"
    ],
    "aws_context_id": "string"
  },
  "remote_disk_throughput": 0,
  "total_initial_remote_disk_size": 0
}
```