---
type: api
title: Update Elasticsearch tiers
description: Updates the size and/or zone count of one or more Elasticsearch topology elements (tiers) within a Deployment.
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/cloud-enterprise/operation/operation-update-deployment-es-resource-tier
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/cloud-enterprise/operation/operation-update-deployment-es-resource-tier
products:
  - Elastic Cloud Enterprise
---

# Update Elasticsearch tiers

## Paths

- `PATCH` `/deployments/{deployment_id}/elasticsearch/{ref_id}/tiers`

#### Path parameters

- `deployment_id` (string) — required
  Identifier for the Deployment
- `ref_id` (string) — required
  User-specified RefId for the Resource (or '_main' if there is only one)

## Description

Updates the size and/or zone count of one or more Elasticsearch topology elements (tiers) within a Deployment.

## Authentication

- Basic: `Authorization: Basic <credentials>`
- Api key: `Authorization: <value>`

## Request body

A map of tier IDs to their desired configuration

`application/json`

- `hot_content` (object) — optional
  Desired configuration for an individual Elasticsearch tier
  - `memory_size` (integer · format: int32) — optional
    The desired memory size in MB for this tier.
  - `zone_count` (integer · format: int32) — optional
    The number of availability zones for this tier. If omitted, the current zone count is preserved.
- `warm` (object) — optional
  Desired configuration for an individual Elasticsearch tier
  - `memory_size` (integer · format: int32) — optional
    The desired memory size in MB for this tier.
  - `zone_count` (integer · format: int32) — optional
    The number of availability zones for this tier. If omitted, the current zone count is preserved.
- `cold` (object) — optional
  Desired configuration for an individual Elasticsearch tier
  - `memory_size` (integer · format: int32) — optional
    The desired memory size in MB for this tier.
  - `zone_count` (integer · format: int32) — optional
    The number of availability zones for this tier. If omitted, the current zone count is preserved.
- `frozen` (object) — optional
  Desired configuration for an individual Elasticsearch tier
  - `memory_size` (integer · format: int32) — optional
    The desired memory size in MB for this tier.
  - `zone_count` (integer · format: int32) — optional
    The number of availability zones for this tier. If omitted, the current zone count is preserved.
- `master` (object) — optional
  Desired configuration for an individual Elasticsearch tier
  - `memory_size` (integer · format: int32) — optional
    The desired memory size in MB for this tier.
  - `zone_count` (integer · format: int32) — optional
    The number of availability zones for this tier. If omitted, the current zone count is preserved.
- `coordinating` (object) — optional
  Desired configuration for an individual Elasticsearch tier
  - `memory_size` (integer · format: int32) — optional
    The desired memory size in MB for this tier.
  - `zone_count` (integer · format: int32) — optional
    The number of availability zones for this tier. If omitted, the current zone count is preserved.
- `ml` (object) — optional
  Desired configuration for an individual Elasticsearch tier
  - `memory_size` (integer · format: int32) — optional
    The desired memory size in MB for this tier.
  - `zone_count` (integer · format: int32) — optional
    The number of availability zones for this tier. If omitted, the current zone count is preserved.

## Responses

#### `202`

The tier configuration was updated and a plan change was initiated.

`application/json`

- `id` (string)
  The id of the deployment
- `name` (string)
  The name of the deployment
- `alias` (string)
  A user-defined alias to use in place of ResourceIds for user-friendly resource URLs
- `resources` (object[])
  List of resources that are part of the deployment after the update operation.
  - `ref_id` (string)
    A locally-unique friendly alias for this Elasticsearch cluster
  - `elasticsearch_cluster_ref_id` (string)
    The Elasticsearch cluster that this resource depends on.
  - `id` (string)
    A system-unique id for the created resource
  - `kind` (string)
    The kind of resource
  - `region` (string)
    Identifier of the region in which this resource runs.
  - `cloud_id` (string)
    An encoded string that provides other Elastic services with the necessary information to connect to this Elasticsearch and Kibana
  - `credentials` (object)
    The username and password for the new Elasticsearch cluster, which is returned from the Elasticsearch cluster `create` command.
    - `username` (string)
      The username of the newly created cluster
    - `password` (string)
      The password of the newly created cluster
  - `secret_token` (string)
    Secret token for using a created resource. Only provided on initial create and absent otherwise.
  - `warnings` (object[])
    List of warnings generated from validating resource updates
    - `code` (string)
      A structured code representing the error type that occurred
    - `message` (string)
      A human readable message describing the warning that occurred
- `shutdown_resources` (object)
  Details about orphaned resources.
  - `elasticsearch` (object[])
    List of orphaned Elasticsearch resources
    - `id` (string)
      The id of the orphaned resource
    - `dependents` (object[])
      List of orphaned dependent resources
      - `id` (string)
        The id of the orphaned resource
      - `kind` (string)
        The kind of resource
  - `kibana` (string[])
    List of orphaned Kibana resource ids
  - `apm` (string[])
    List of orphaned APM resource ids
  - `appsearch` (string[])
    List of orphaned AppSearch resource ids
  - `enterprise_search` (string[])
    List of orphaned Enterprise Search resource ids
  - `integrations_server` (string[])
    List of orphaned Integrations Server resource ids
- `diagnostics` (object)
  Describes the diagnostics for a given Deployment-modifying payload
  - `creates` (object)
    Holds diagnostics for resources that will be created
    - `elasticsearch` (object[])
      Diagnostics for Elasticsearch clusters
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name for the cluster (defaults to the generated cluster id if not specified)
      - `backend_plan` (object)
        The backend plan as JSON
    - `kibana` (object[])
      Diagnostics for Kibanas
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `apm` (object[])
      Diagnostics for APMs
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `integrations_server` (object[])
      Diagnostics for Integrations Server
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `appsearch` (object[])
      Diagnostics for AppSearches
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `enterprise_search` (object[])
      Diagnostics for Enterprise Search resources
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
  - `updates` (object)
    Holds diagnostics for existing resources that might be updated
    - `elasticsearch` (object[])
      Diagnostics for Elasticsearch clusters
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name for the cluster (defaults to the generated cluster id if not specified)
      - `backend_plan` (object)
        The backend plan as JSON
    - `kibana` (object[])
      Diagnostics for Kibanas
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `apm` (object[])
      Diagnostics for APMs
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `integrations_server` (object[])
      Diagnostics for Integrations Server
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `appsearch` (object[])
      Diagnostics for AppSearches
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
    - `enterprise_search` (object[])
      Diagnostics for Enterprise Search resources
      - `ref_id` (string)
        A locally-unique user-specified id
      - `display_name` (string)
        The human readable name (defaults to the generated cluster id if not specified)
      - `elasticsearch_cluster_ref_id` (string)
        The user-specified id of the Elasticsearch Cluster that this will link to
      - `backend_plan` (object)
        The backend plan as JSON
- `settings` (object)
  Additional configuration about the current deployment object.
  - `traffic_filter_settings` (object)
    The configuration settings for the traffic filter.
    - `rulesets` (string[])
      IDs of the traffic filter rulesets
  - `observability` (object)
    The observability settings for a deployment
    - `logging` (object)
      The logging settings for a deployment
      - `destination` (object)
        The destination to send logs and metrics to
        - `deployment_id` (string)
          The deployment to send logs and/or metrics to. Contains either the deployment's ID or 'self'.
        - `ref_id` (string)
          RefId of the Elasticsearch cluster to send logs and/or metrics to. If not specified, refId is resolved automatically as long as the destination deployment contains a single Elasticsearch resource.
    - `metrics` (object)
      The metrics settings for a deployment
      - `destination` (object)
        The destination to send logs and metrics to
        - `deployment_id` (string)
          The deployment to send logs and/or metrics to. Contains either the deployment's ID or 'self'.
        - `ref_id` (string)
          RefId of the Elasticsearch cluster to send logs and/or metrics to. If not specified, refId is resolved automatically as long as the destination deployment contains a single Elasticsearch resource.
      - `force_legacy_monitoring` (boolean)
        Set to true to force the deployment to use legacy monitoring instead of Metricbeat-based monitoring. Only available for versions lower than 9.0.
  - `autoscaling_enabled` (boolean)
    If autoscaling is enabled for this deployment.
  - `auto_ops` (object)
    AutoOps settings for this deployment.
    - `status` (enum)
      See AutoOps integration status for this deployment.
      Values: `connected`, `not_connected`, `excluded`
  - `byok` (object)
    Information required to create a Bring Your Own Key (BYOK) deployment.
    - `key_resource_path` (string)
      Key path (i.e arn:aws:kms:us-east-1:1234567890:key/12345678-0000-0000-0000-000000000000).
  - `solution_type` (string)
    An optional string that declares the deployment's expected application. Example supported values are: elasticsearch, observability, security.
#### `404`

* The Deployment specified by {deployment_id} cannot be found. (code: `deployments.deployment_not_found`)
* The Resource specified by {ref_id} cannot be found. (code: `deployments.deployment_resource_not_found`)
* One or more tier IDs in the request body are not valid for this deployment. (code: `deployments.tier_not_found`)

`application/json`

- `errors` (object[])
  A list of errors that occurred in the failing request
  - `code` (string)
    A structured code representing the error type that occurred
  - `message` (string)
    A human readable message describing the error that occurred
  - `fields` (string[])
    If the error can be tied to a specific field or fields in the user request, this lists those fields
##### Response headers

- `x-cloud-error-codes` (enum)
  The error codes associated with the response

#### `500`

We have failed you. (code: `deployments.metadata_internal_error`)

`application/json`

- `errors` (object[])
  A list of errors that occurred in the failing request
  - `code` (string)
    A structured code representing the error type that occurred
  - `message` (string)
    A human readable message describing the error that occurred
  - `fields` (string[])
    If the error can be tied to a specific field or fields in the user request, this lists those fields
##### Response headers

- `x-cloud-error-codes` (enum)
  The error codes associated with the response

## Code examples

#### curl

```curl
curl -X PATCH "${API_URL}/deployments/${DEPLOYMENT_ID}/elasticsearch/${REF_ID}/tiers" \
  -u "${USERNAME}:${PASSWORD}" \
  -H "Content-Type: application/json" \
  -d '{}'
```