elasticsearch/docs/reference/autoscaling/apis/get-autoscaling-capacity.asciidoc

[role="xpack"]
[[autoscaling-get-autoscaling-capacity]]
=== Get autoscaling capacity API
++++
<titleabbrev>Get autoscaling capacity</titleabbrev>
++++

NOTE: {cloud-only}

Get autoscaling capacity.

[[autoscaling-get-autoscaling-capacity-request]]
==== {api-request-title}

[source,console]
--------------------------------------------------
GET /_autoscaling/capacity/
--------------------------------------------------
// TEST

[[autoscaling-get-autoscaling-capacity-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have
`manage_autoscaling` cluster privileges. For more information, see
<<security-privileges>>.

[[autoscaling-get-autoscaling-capacity-desc]]
==== {api-description-title}

This API gets the current autoscaling capacity based on the configured
autoscaling policy. This API will return information to size the cluster
appropriately to the current workload.

The `required_capacity` is calculated as the max of the `required_capacity`
result of all individual deciders that are enabled for the policy.

The operator should verify that the `current_nodes` match
the operator's knowledge of the cluster to avoid making autoscaling decisions
based on stale or incomplete information.

The response contains decider-specific information you can use to diagnose how
and why autoscaling determined a certain capacity was required. This information
is provided for diagnosis only. Do not use this information to make autoscaling
decisions.

[role="child_attributes"]
[[autoscaling-get-autoscaling-capacity-api-response-body]]
==== {api-response-body-title}

`policies`::
(object)
Contains the map of policy name to capacity result
+
.Properties of `policies`
[%collapsible%open]
====
`<policy_name>`::
(object)
Contains capacity information for the policy
+
.Properties of `<policy_name>`
[%collapsible%open]
=====
`required_capacity`::
(object)
Contains the required capacity for the policy.
+
.Properties of `required_capacity`
[%collapsible%open]
======
`node`::
(object)
Contains the minimum node sizes required per node, ensuring that individual
shards or ML jobs can fit into a single node.
+
.Properties of `node`
[%collapsible%open]
=======
`storage`::
(integer)
Bytes of storage required per node.

`memory`::
(integer)
Bytes of memory required per node.

=======
`total`::
(object)
Contains the total size required for the policy.
+
.Properties of `total`
[%collapsible%open]
=======
`storage`::
(integer)
Total bytes of storage required for the policy.

`memory`::
(integer)
Total bytes of memory required for the policy.
=======
======
`current_capacity`::
(object)
Contains the current capacity for nodes governed by the policy, i.e. the nodes
that {es} bases its calculation on.
+
.Properties of `current_capacity`
[%collapsible%open]
======
`node`::
(object)
Contains the maximum sizes of nodes governed by the policy.
+
.Properties of `node`
[%collapsible%open]
=======
`storage`::
(integer)
Maximum bytes of storage of a node.

`memory`::
(integer)
Maximum bytes of memory of a node.

=======
`total`::
(object)
Contains the current total storage and memory sizes for nodes governed by the policy.
+
.Properties of `total`
[%collapsible%open]
=======
`storage`::
(integer)
Current bytes of storage available for the policy.

`memory`::
(integer)
Current bytes of memory available for the policy.
=======
======
`current_nodes`::
(array of objects)
List of nodes used for capacity calculation.
+
.Properties of elements in `current_nodes`
[%collapsible%open]
======
`name`::
(string)
Name of the node.
======
`deciders`::
(object)
The capacity results from individual deciders, allowing insight into how the
outer level `required_capacity` was calculated.
+
.Properties of `deciders`
[%collapsible%open]
=======
`<decider_name>`::
(object)
The capacity result for a specific decider enabled for the policy.
+
.Properties of `<decider_name>`
[%collapsible%open]
========
`required_capacity`::
(object)
Required capacity determined by the decider.
+
.Properties of `required_capacity`
[%collapsible%open]
=========
`node`::
(object)
Contains the minimum node sizes required per node, ensuring that individual
shards or {ml} jobs can fit into a single node.
+
.Properties of `node`
[%collapsible%open]
==========
`storage`::
(integer)
Bytes of storage required per node.

`memory`::
(integer)
Bytes of memory required per node.

==========
`total`::
(object)
Contains the total size required for the policy.
+
.Properties of `total`
[%collapsible%open]
==========
`storage`::
(integer)
Total bytes of storage required for the policy.

`memory`::
(integer)
Total bytes of memory required for the policy.
==========
=========
`reason_summary`::
(string)
Description of the basis for the decider's result.

`reason_details`::
(object)
A per-decider structure containing details about the basis for the deciders' result.
The contents should not be relied on for application purposes and are not subject
to backwards compatibility guarantees.
========
=======
=====
====

[[autoscaling-get-autoscaling-capacity-examples]]
==== {api-examples-title}

This example retrieves the current autoscaling capacity.

[source,console]
--------------------------------------------------
GET /_autoscaling/capacity
--------------------------------------------------
// TEST

The API returns the following result:

[source,console-result]
--------------------------------------------------
{
  policies: {}
}
--------------------------------------------------