2026/10/28 - Amazon Elastic Compute Cloud - 1 new4 updated api methods
Changes Amazon EC2 Capacity Manager adds supportability checks and capacity fulfillment metrics. Use GetCapacityManagerSupportabilityScores to score how well instance types and Availability Zones can support a capacity request, and GetCapacityManagerMetricData to retrieve fulfillment metrics.
Scores how well each instance type and Availability Zone combination can support a capacity request, based on current Amazon EC2 capacity. The response includes a score for each combination and an aggregate score for all combinations in the request. This action doesn't launch or reserve instances, and a score doesn't guarantee that a later launch will succeed.
Call this action in the Region where you turned on Capacity Manager. A single request can include Availability Zones in any Region. Real-time supportability checks are available only to Amazon Web Services Support customers on the Unified Operations plan.
For more information, see Check supportability in the Amazon EC2 User Guide.
See also: AWS API Documentation
Request Syntax
client.get_capacity_manager_supportability_scores(
MarketType='on-demand'|'spot',
CapacityAmount=123,
CapacityUnit='vcpus'|'instances',
CapacityAvailabilityZoneIds=[
'string',
],
InstanceTypes=[
'string',
],
InstanceRequirementsWithMetadata={
'ArchitectureTypes': [
'i386'|'x86_64'|'arm64'|'x86_64_mac'|'arm64_mac',
],
'VirtualizationTypes': [
'hvm'|'paravirtual',
],
'InstanceRequirements': {
'VCpuCount': {
'Min': 123,
'Max': 123
},
'MemoryMiB': {
'Min': 123,
'Max': 123
},
'CpuManufacturers': [
'intel'|'amd'|'amazon-web-services'|'apple',
],
'MemoryGiBPerVCpu': {
'Min': 123.0,
'Max': 123.0
},
'ExcludedInstanceTypes': [
'string',
],
'InstanceGenerations': [
'current'|'previous',
],
'SpotMaxPricePercentageOverLowestPrice': 123,
'OnDemandMaxPricePercentageOverLowestPrice': 123,
'BareMetal': 'included'|'required'|'excluded',
'BurstablePerformance': 'included'|'required'|'excluded',
'RequireHibernateSupport': True|False,
'NetworkInterfaceCount': {
'Min': 123,
'Max': 123
},
'LocalStorage': 'included'|'required'|'excluded',
'LocalStorageTypes': [
'hdd'|'ssd',
],
'TotalLocalStorageGB': {
'Min': 123.0,
'Max': 123.0
},
'BaselineEbsBandwidthMbps': {
'Min': 123,
'Max': 123
},
'AcceleratorTypes': [
'gpu'|'fpga'|'inference'|'media',
],
'AcceleratorCount': {
'Min': 123,
'Max': 123
},
'AcceleratorManufacturers': [
'amazon-web-services'|'amd'|'nvidia'|'xilinx'|'habana',
],
'AcceleratorNames': [
'a100'|'inferentia'|'k520'|'k80'|'m60'|'radeon-pro-v520'|'t4'|'vu9p'|'v100'|'a10g'|'h100'|'t4g'|'l40s'|'l4'|'gaudi-hl-205'|'inferentia2'|'trainium'|'trainium2'|'u30',
],
'AcceleratorTotalMemoryMiB': {
'Min': 123,
'Max': 123
},
'NetworkBandwidthGbps': {
'Min': 123.0,
'Max': 123.0
},
'AllowedInstanceTypes': [
'string',
],
'MaxSpotPriceAsPercentageOfOptimalOnDemandPrice': 123,
'BaselinePerformanceFactors': {
'Cpu': {
'References': [
{
'InstanceFamily': 'string'
},
]
}
},
'RequireEncryptionInTransit': True|False
}
},
DryRun=True|False
)
string
[REQUIRED]
The capacity market to score.
integer
[REQUIRED]
The amount of capacity that you need, in the unit that you specify for CapacityUnit. Each score is relative to this amount.
string
[REQUIRED]
The unit for CapacityAmount.
list
[REQUIRED]
The IDs of the Availability Zones to score, such as use1-az1. You can specify Availability Zones in different Regions. You can specify up to 10 Availability Zones.
(string) --
list
The instance types to score. You can specify up to 50 instance types.
Specify either InstanceTypes or InstanceRequirementsWithMetadata, but not both.
(string) --
dict
The attributes that the instance types must have, such as vCPU and memory ranges. Capacity Manager resolves the attributes into matching instance types and scores each one.
Specify either InstanceTypes or InstanceRequirementsWithMetadata, but not both.
ArchitectureTypes (list) --
The architecture type.
(string) --
VirtualizationTypes (list) --
The virtualization type.
(string) --
InstanceRequirements (dict) --
The attributes for the instance types. When you specify instance attributes, Amazon EC2 will identify instance types with those attributes.
VCpuCount (dict) -- [REQUIRED]
The minimum and maximum number of vCPUs.
Min (integer) -- [REQUIRED]
The minimum number of vCPUs. To specify no minimum limit, specify 0.
Max (integer) --
The maximum number of vCPUs. To specify no maximum limit, omit this parameter.
MemoryMiB (dict) -- [REQUIRED]
The minimum and maximum amount of memory, in MiB.
Min (integer) -- [REQUIRED]
The minimum amount of memory, in MiB. To specify no minimum limit, specify 0.
Max (integer) --
The maximum amount of memory, in MiB. To specify no maximum limit, omit this parameter.
CpuManufacturers (list) --
The CPU manufacturers to include.
For instance types with Intel CPUs, specify intel.
For instance types with AMD CPUs, specify amd.
For instance types with Amazon Web Services CPUs, specify amazon-web-services.
For instance types with Apple CPUs, specify apple.
Default: Any manufacturer
(string) --
MemoryGiBPerVCpu (dict) --
The minimum and maximum amount of memory per vCPU, in GiB.
Default: No minimum or maximum limits
Min (float) --
The minimum amount of memory per vCPU, in GiB. To specify no minimum limit, omit this parameter.
Max (float) --
The maximum amount of memory per vCPU, in GiB. To specify no maximum limit, omit this parameter.
ExcludedInstanceTypes (list) --
The instance types to exclude.
You can use strings with one or more wild cards, represented by an asterisk ( *), to exclude an instance family, type, size, or generation. The following are examples: m5.8xlarge, c5*.*, m5a.*, r*, *3*.
For example, if you specify c5*,Amazon EC2 will exclude the entire C5 instance family, which includes all C5a and C5n instance types. If you specify m5a.*, Amazon EC2 will exclude all the M5a instance types, but not the M5n instance types.
Default: No excluded instance types
(string) --
InstanceGenerations (list) --
Indicates whether current or previous generation instance types are included. The current generation instance types are recommended for use. Current generation instance types are typically the latest two to three generations in each instance family. For more information, see Instance types in the Amazon EC2 User Guide.
For current generation instance types, specify current.
For previous generation instance types, specify previous.
Default: Current and previous generation instance types
(string) --
SpotMaxPricePercentageOverLowestPrice (integer) --
[Price protection] The price protection threshold for Spot Instances, as a percentage higher than an identified Spot price. The identified Spot price is the Spot price of the lowest priced current generation C, M, or R instance type with your specified attributes. If no current generation C, M, or R instance type matches your attributes, then the identified Spot price is from the lowest priced current generation instance types, and failing that, from the lowest priced previous generation instance types that match your attributes. When Amazon EC2 selects instance types with your attributes, it will exclude instance types whose Spot price exceeds your specified threshold.
The parameter accepts an integer, which Amazon EC2 interprets as a percentage.
If you set TargetCapacityUnitType to vcpu or memory-mib, the price protection threshold is applied based on the per-vCPU or per-memory price instead of the per-instance price.
This parameter is not supported for GetSpotPlacementScores and GetInstanceTypesFromInstanceRequirements.
Default: 100
OnDemandMaxPricePercentageOverLowestPrice (integer) --
[Price protection] The price protection threshold for On-Demand Instances, as a percentage higher than an identified On-Demand price. The identified On-Demand price is the price of the lowest priced current generation C, M, or R instance type with your specified attributes. When Amazon EC2 selects instance types with your attributes, it will exclude instance types whose price exceeds your specified threshold.
The parameter accepts an integer, which Amazon EC2 interprets as a percentage.
To indicate no price protection threshold, specify a high value, such as 999999.
This parameter is not supported for GetSpotPlacementScores and GetInstanceTypesFromInstanceRequirements.
Default: 20
BareMetal (string) --
Indicates whether bare metal instance types must be included, excluded, or required.
To include bare metal instance types, specify included.
To require only bare metal instance types, specify required.
To exclude bare metal instance types, specify excluded.
Default: excluded
BurstablePerformance (string) --
Indicates whether burstable performance T instance types are included, excluded, or required. For more information, see Burstable performance instances.
To include burstable performance instance types, specify included.
To require only burstable performance instance types, specify required.
To exclude burstable performance instance types, specify excluded.
Default: excluded
RequireHibernateSupport (boolean) --
Indicates whether instance types must support hibernation for On-Demand Instances.
This parameter is not supported for GetSpotPlacementScores.
Default: false
NetworkInterfaceCount (dict) --
The minimum and maximum number of network interfaces.
Default: No minimum or maximum limits
Min (integer) --
The minimum number of network interfaces. To specify no minimum limit, omit this parameter.
Max (integer) --
The maximum number of network interfaces. To specify no maximum limit, omit this parameter.
LocalStorage (string) --
Indicates whether instance types with instance store volumes are included, excluded, or required. For more information, Amazon EC2 instance store in the Amazon EC2 User Guide.
To include instance types with instance store volumes, specify included.
To require only instance types with instance store volumes, specify required.
To exclude instance types with instance store volumes, specify excluded.
Default: included
LocalStorageTypes (list) --
The type of local storage that is required.
For instance types with hard disk drive (HDD) storage, specify hdd.
For instance types with solid state drive (SSD) storage, specify ssd.
Default: hdd and ssd
(string) --
TotalLocalStorageGB (dict) --
The minimum and maximum amount of total local storage, in GB.
Default: No minimum or maximum limits
Min (float) --
The minimum amount of total local storage, in GB. To specify no minimum limit, omit this parameter.
Max (float) --
The maximum amount of total local storage, in GB. To specify no maximum limit, omit this parameter.
BaselineEbsBandwidthMbps (dict) --
The minimum and maximum baseline bandwidth to Amazon EBS, in Mbps. For more information, see Amazon EBS–optimized instances in the Amazon EC2 User Guide.
Default: No minimum or maximum limits
Min (integer) --
The minimum baseline bandwidth, in Mbps. To specify no minimum limit, omit this parameter.
Max (integer) --
The maximum baseline bandwidth, in Mbps. To specify no maximum limit, omit this parameter.
AcceleratorTypes (list) --
The accelerator types that must be on the instance type.
For instance types with FPGA accelerators, specify fpga.
For instance types with GPU accelerators, specify gpu.
For instance types with Inference accelerators, specify inference.
For instance types with Media accelerators, specify media.
Default: Any accelerator type
(string) --
AcceleratorCount (dict) --
The minimum and maximum number of accelerators (GPUs, FPGAs, or Amazon Web Services Inferentia chips) on an instance.
To exclude accelerator-enabled instance types, set Max to 0.
Default: No minimum or maximum limits
Min (integer) --
The minimum number of accelerators. To specify no minimum limit, omit this parameter.
Max (integer) --
The maximum number of accelerators. To specify no maximum limit, omit this parameter. To exclude accelerator-enabled instance types, set Max to 0.
AcceleratorManufacturers (list) --
Indicates whether instance types must have accelerators by specific manufacturers.
For instance types with Amazon Web Services devices, specify amazon-web-services.
For instance types with AMD devices, specify amd.
For instance types with Habana devices, specify habana.
For instance types with NVIDIA devices, specify nvidia.
For instance types with Xilinx devices, specify xilinx.
Default: Any manufacturer
(string) --
AcceleratorNames (list) --
The accelerators that must be on the instance type.
For instance types with NVIDIA A10G GPUs, specify a10g.
For instance types with NVIDIA A100 GPUs, specify a100.
For instance types with NVIDIA H100 GPUs, specify h100.
For instance types with Amazon Web Services Inferentia chips, specify inferentia.
For instance types with Amazon Web Services Inferentia2 chips, specify inferentia2.
For instance types with Habana Gaudi HL-205 GPUs, specify gaudi-hl-205.
For instance types with NVIDIA GRID K520 GPUs, specify k520.
For instance types with NVIDIA K80 GPUs, specify k80.
For instance types with NVIDIA L4 GPUs, specify l4.
For instance types with NVIDIA L40S GPUs, specify l40s.
For instance types with NVIDIA M60 GPUs, specify m60.
For instance types with AMD Radeon Pro V520 GPUs, specify radeon-pro-v520.
For instance types with Amazon Web Services Trainium chips, specify trainium.
For instance types with Amazon Web Services Trainium2 chips, specify trainium2.
For instance types with NVIDIA T4 GPUs, specify t4.
For instance types with NVIDIA T4G GPUs, specify t4g.
For instance types with Xilinx U30 cards, specify u30.
For instance types with Xilinx VU9P FPGAs, specify vu9p.
For instance types with NVIDIA V100 GPUs, specify v100.
Default: Any accelerator
(string) --
AcceleratorTotalMemoryMiB (dict) --
The minimum and maximum amount of total accelerator memory, in MiB.
Default: No minimum or maximum limits
Min (integer) --
The minimum amount of accelerator memory, in MiB. To specify no minimum limit, omit this parameter.
Max (integer) --
The maximum amount of accelerator memory, in MiB. To specify no maximum limit, omit this parameter.
NetworkBandwidthGbps (dict) --
The minimum and maximum amount of baseline network bandwidth, in gigabits per second (Gbps). For more information, see Amazon EC2 instance network bandwidth in the Amazon EC2 User Guide.
Default: No minimum or maximum limits
Min (float) --
The minimum amount of network bandwidth, in Gbps. To specify no minimum limit, omit this parameter.
Max (float) --
The maximum amount of network bandwidth, in Gbps. To specify no maximum limit, omit this parameter.
AllowedInstanceTypes (list) --
The instance types to apply your specified attributes against. All other instance types are ignored, even if they match your specified attributes.
You can use strings with one or more wild cards, represented by an asterisk ( *), to allow an instance type, size, or generation. The following are examples: m5.8xlarge, c5*.*, m5a.*, r*, *3*.
For example, if you specify c5*,Amazon EC2 will allow the entire C5 instance family, which includes all C5a and C5n instance types. If you specify m5a.*, Amazon EC2 will allow all the M5a instance types, but not the M5n instance types.
Default: All instance types
(string) --
MaxSpotPriceAsPercentageOfOptimalOnDemandPrice (integer) --
[Price protection] The price protection threshold for Spot Instances, as a percentage of an identified On-Demand price. The identified On-Demand price is the price of the lowest priced current generation C, M, or R instance type with your specified attributes. If no current generation C, M, or R instance type matches your attributes, then the identified price is from the lowest priced current generation instance types, and failing that, from the lowest priced previous generation instance types that match your attributes. When Amazon EC2 selects instance types with your attributes, it will exclude instance types whose price exceeds your specified threshold.
The parameter accepts an integer, which Amazon EC2 interprets as a percentage.
If you set TargetCapacityUnitType to vcpu or memory-mib, the price protection threshold is based on the per vCPU or per memory price instead of the per instance price.
BaselinePerformanceFactors (dict) --
The baseline performance to consider, using an instance family as a baseline reference. The instance family establishes the lowest acceptable level of performance. Amazon EC2 uses this baseline to guide instance type selection, but there is no guarantee that the selected instance types will always exceed the baseline for every application. Currently, this parameter only supports CPU performance as a baseline performance factor. For more information, see Performance protection in the Amazon EC2 User Guide.
Cpu (dict) --
The CPU performance to consider, using an instance family as the baseline reference.
References (list) --
Specify an instance family to use as the baseline reference for CPU performance. All instance types that match your specified attributes will be compared against the CPU performance of the referenced instance family, regardless of CPU manufacturer or architecture differences.
(dict) --
Specify an instance family to use as the baseline reference for CPU performance. All instance types that match your specified attributes will be compared against the CPU performance of the referenced instance family, regardless of CPU manufacturer or architecture.
InstanceFamily (string) --
The instance family to use as a baseline reference.
The following instance families are not supported for performance protection:
c1
g3 | g3s
hpc7g
m1 | m2
mac1 | mac2 | mac2-m1ultra | mac2-m2 | mac2-m2pro
p3dn | p4d | p5
t1
u-12tb1 | u-18tb1 | u-24tb1 | u-3tb1 | u-6tb1 | u-9tb1 | u7i-12tb | u7in-16tb | u7in-24tb | u7in-32tb
If you enable performance protection by specifying a supported instance family, the returned instance types will exclude the above unsupported instance families.
If you specify an unsupported instance family as a value for baseline performance, the API returns an empty response for GetInstanceTypesFromInstanceRequirements and an exception for CreateFleet, RequestSpotFleet, ModifyFleet, and ModifySpotFleetRequest.
RequireEncryptionInTransit (boolean) --
Specifies whether instance types must support encrypting in-transit traffic between instances. For more information, including the supported instance types, see Encryption in transit in the Amazon EC2 User Guide.
Default: false
boolean
Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.
dict
Response Syntax
{
'AggregateScore': 'high'|'medium'|'low',
'CapacityManagerSupportabilityScores': [
{
'InstanceType': 'string',
'AvailabilityZoneId': 'string',
'Score': 'high'|'medium'|'low'
},
]
}
Response Structure
(dict) --
AggregateScore (string) --
The score for all instance type and Availability Zone combinations in the request together. A high aggregate score with lower individual scores means that no single combination can support the full request, but the combinations together can.
CapacityManagerSupportabilityScores (list) --
The score for each instance type and Availability Zone combination in the request.
(dict) --
The supportability score for a single instance type and Availability Zone combination.
InstanceType (string) --
The instance type.
AvailabilityZoneId (string) --
The ID of the Availability Zone.
Score (string) --
How well the combination can support the requested capacity right now. high means that the combination holds several times the requested amount. medium means that it can cover the request with little to spare. low means that it holds less than the requested amount.
{'AvailabilityZone': 'string',
'AvailabilityZoneId': 'string',
'InstanceRequirements': {'AcceleratorCount': {'Max': 'integer',
'Min': 'integer'},
'AcceleratorManufacturers': ['amazon-web-services | '
'amd | nvidia | xilinx '
'| habana'],
'AcceleratorNames': ['a100 | inferentia | k520 | k80 '
'| m60 | radeon-pro-v520 | t4 | '
'vu9p | v100 | a10g | h100 | '
't4g | l40s | l4 | gaudi-hl-205 '
'| inferentia2 | trainium | '
'trainium2 | u30'],
'AcceleratorTotalMemoryMiB': {'Max': 'integer',
'Min': 'integer'},
'AcceleratorTypes': ['gpu | fpga | inference | '
'media'],
'AllowedInstanceTypes': ['string'],
'BareMetal': 'included | required | excluded',
'BaselineEbsBandwidthMbps': {'Max': 'integer',
'Min': 'integer'},
'BaselinePerformanceFactors': {'Cpu': {'References': [{'InstanceFamily': 'string'}]}},
'BurstablePerformance': 'included | required | '
'excluded',
'CpuManufacturers': ['intel | amd | '
'amazon-web-services | apple'],
'ExcludedInstanceTypes': ['string'],
'InstanceGenerations': ['current | previous'],
'LocalStorage': 'included | required | excluded',
'LocalStorageTypes': ['hdd | ssd'],
'MaxSpotPriceAsPercentageOfOptimalOnDemandPrice': 'integer',
'MemoryGiBPerVCpu': {'Max': 'double',
'Min': 'double'},
'MemoryMiB': {'Max': 'integer', 'Min': 'integer'},
'NetworkBandwidthGbps': {'Max': 'double',
'Min': 'double'},
'NetworkInterfaceCount': {'Max': 'integer',
'Min': 'integer'},
'OnDemandMaxPricePercentageOverLowestPrice': 'integer',
'RequireEncryptionInTransit': 'boolean',
'RequireHibernateSupport': 'boolean',
'SpotMaxPricePercentageOverLowestPrice': 'integer',
'TotalLocalStorageGB': {'Max': 'double',
'Min': 'double'},
'VCpuCount': {'Max': 'integer', 'Min': 'integer'}}}
{'CapacityReservationFleets': {'AvailabilityZone': 'string',
'AvailabilityZoneId': 'string',
'InstanceRequirements': {'AcceleratorCount': {'Max': 'integer',
'Min': 'integer'},
'AcceleratorManufacturers': ['amazon-web-services '
'| '
'amd '
'| '
'nvidia '
'| '
'xilinx '
'| '
'habana'],
'AcceleratorNames': ['a100 '
'| '
'inferentia '
'| '
'k520 '
'| '
'k80 '
'| '
'm60 '
'| '
'radeon-pro-v520 '
'| '
't4 '
'| '
'vu9p '
'| '
'v100 '
'| '
'a10g '
'| '
'h100 '
'| '
't4g '
'| '
'l40s '
'| '
'l4 '
'| '
'gaudi-hl-205 '
'| '
'inferentia2 '
'| '
'trainium '
'| '
'trainium2 '
'| '
'u30'],
'AcceleratorTotalMemoryMiB': {'Max': 'integer',
'Min': 'integer'},
'AcceleratorTypes': ['gpu '
'| '
'fpga '
'| '
'inference '
'| '
'media'],
'AllowedInstanceTypes': ['string'],
'BareMetal': 'included '
'| '
'required '
'| '
'excluded',
'BaselineEbsBandwidthMbps': {'Max': 'integer',
'Min': 'integer'},
'BaselinePerformanceFactors': {'Cpu': {'References': [{'InstanceFamily': 'string'}]}},
'BurstablePerformance': 'included '
'| '
'required '
'| '
'excluded',
'CpuManufacturers': ['intel '
'| '
'amd '
'| '
'amazon-web-services '
'| '
'apple'],
'ExcludedInstanceTypes': ['string'],
'InstanceGenerations': ['current '
'| '
'previous'],
'LocalStorage': 'included '
'| '
'required '
'| '
'excluded',
'LocalStorageTypes': ['hdd '
'| '
'ssd'],
'MaxSpotPriceAsPercentageOfOptimalOnDemandPrice': 'integer',
'MemoryGiBPerVCpu': {'Max': 'double',
'Min': 'double'},
'MemoryMiB': {'Max': 'integer',
'Min': 'integer'},
'NetworkBandwidthGbps': {'Max': 'double',
'Min': 'double'},
'NetworkInterfaceCount': {'Max': 'integer',
'Min': 'integer'},
'OnDemandMaxPricePercentageOverLowestPrice': 'integer',
'RequireEncryptionInTransit': 'boolean',
'RequireHibernateSupport': 'boolean',
'SpotMaxPricePercentageOverLowestPrice': 'integer',
'TotalLocalStorageGB': {'Max': 'double',
'Min': 'double'},
'VCpuCount': {'Max': 'integer',
'Min': 'integer'}}}}
{'MetricNames': {'avg-inst-az-count-per-requested-vcpu',
'capacity-request-fulfillment-rate',
'capacity-total-fulfilled-vcpu',
'capacity-total-requested-vcpu',
'inst-az-fulfillment-rate',
'spot-avg-inst-az-count-per-requested-vcpu',
'spot-capacity-request-fulfillment-rate',
'spot-capacity-total-fulfilled-vcpu',
'spot-capacity-total-requested-vcpu',
'spot-inst-az-fulfillment-rate'}}
Response {'MetricDataResults': {'MetricValues': {'Metric': {'avg-inst-az-count-per-requested-vcpu',
'capacity-request-fulfillment-rate',
'capacity-total-fulfilled-vcpu',
'capacity-total-requested-vcpu',
'inst-az-fulfillment-rate',
'spot-avg-inst-az-count-per-requested-vcpu',
'spot-capacity-request-fulfillment-rate',
'spot-capacity-total-fulfilled-vcpu',
'spot-capacity-total-requested-vcpu',
'spot-inst-az-fulfillment-rate'}}}}
Retrieves capacity usage metrics for your EC2 resources. Returns time-series data for metrics like unused capacity, utilization rates, and costs across On-Demand, Spot, and Capacity Reservations. Data can be grouped and filtered by various dimensions such as region, account, and instance family.
See also: AWS API Documentation
Request Syntax
client.get_capacity_manager_metric_data(
MetricNames=[
'reservation-total-capacity-hrs-vcpu'|'reservation-total-capacity-hrs-inst'|'reservation-max-size-vcpu'|'reservation-max-size-inst'|'reservation-min-size-vcpu'|'reservation-min-size-inst'|'reservation-unused-total-capacity-hrs-vcpu'|'reservation-unused-total-capacity-hrs-inst'|'reservation-unused-total-estimated-cost'|'reservation-max-unused-size-vcpu'|'reservation-max-unused-size-inst'|'reservation-min-unused-size-vcpu'|'reservation-min-unused-size-inst'|'reservation-max-utilization'|'reservation-min-utilization'|'reservation-avg-utilization-vcpu'|'reservation-avg-utilization-inst'|'reservation-total-count'|'reservation-total-estimated-cost'|'reservation-avg-future-size-vcpu'|'reservation-avg-future-size-inst'|'reservation-min-future-size-vcpu'|'reservation-min-future-size-inst'|'reservation-max-future-size-vcpu'|'reservation-max-future-size-inst'|'reservation-avg-committed-size-vcpu'|'reservation-avg-committed-size-inst'|'reservation-max-committed-size-vcpu'|'reservation-max-committed-size-inst'|'reservation-min-committed-size-vcpu'|'reservation-min-committed-size-inst'|'reserved-total-usage-hrs-vcpu'|'reserved-total-usage-hrs-inst'|'reserved-total-estimated-cost'|'unreserved-total-usage-hrs-vcpu'|'unreserved-total-usage-hrs-inst'|'unreserved-total-estimated-cost'|'spot-total-usage-hrs-vcpu'|'spot-total-usage-hrs-inst'|'spot-total-estimated-cost'|'spot-avg-run-time-before-interruption-inst'|'spot-max-run-time-before-interruption-inst'|'spot-min-run-time-before-interruption-inst'|'spot-total-interruptions-inst'|'spot-total-interruptions-vcpu'|'spot-total-count-inst'|'spot-total-count-vcpu'|'spot-interruption-rate-inst'|'spot-interruption-rate-vcpu'|'capacity-total-requested-vcpu'|'capacity-total-fulfilled-vcpu'|'spot-capacity-total-requested-vcpu'|'spot-capacity-total-fulfilled-vcpu'|'capacity-request-fulfillment-rate'|'avg-inst-az-count-per-requested-vcpu'|'inst-az-fulfillment-rate'|'spot-capacity-request-fulfillment-rate'|'spot-avg-inst-az-count-per-requested-vcpu'|'spot-inst-az-fulfillment-rate',
],
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
Period=123,
GroupBy=[
'resource-region'|'availability-zone-id'|'account-id'|'account-name'|'instance-family'|'instance-type'|'instance-platform'|'reservation-arn'|'reservation-id'|'reservation-type'|'reservation-create-timestamp'|'reservation-start-timestamp'|'reservation-end-timestamp'|'reservation-end-date-type'|'tenancy'|'reservation-state'|'reservation-instance-match-criteria'|'reservation-unused-financial-owner',
],
FilterBy=[
{
'DimensionCondition': {
'Dimension': 'resource-region'|'availability-zone-id'|'account-id'|'account-name'|'instance-family'|'instance-type'|'instance-platform'|'reservation-arn'|'reservation-id'|'reservation-type'|'reservation-create-timestamp'|'reservation-start-timestamp'|'reservation-end-timestamp'|'reservation-end-date-type'|'tenancy'|'reservation-state'|'reservation-instance-match-criteria'|'reservation-unused-financial-owner',
'Comparison': 'equals'|'in',
'Values': [
'string',
]
}
},
],
MaxResults=123,
NextToken='string',
DryRun=True|False
)
list
[REQUIRED]
The names of the metrics to retrieve. Maximum of 10 metrics per request.
(string) --
datetime
[REQUIRED]
The start time for the metric data query, in ISO 8601 format. The time range (end time - start time) must be a multiple of the specified period.
datetime
[REQUIRED]
The end time for the metric data query, in ISO 8601 format. If the end time is beyond the latest ingested data, it will be automatically adjusted to the latest available data point.
integer
[REQUIRED]
The granularity, in seconds, of the returned data points.
list
The dimensions by which to group the metric data. This determines how the data is aggregated and returned.
(string) --
list
Conditions to filter the metric data. Each filter specifies a dimension, comparison operator ('equals', 'in'), and values to match against.
(dict) --
Represents a filter condition for Capacity Manager queries. Contains dimension-based filtering criteria used to narrow down metric data and dimension results.
DimensionCondition (dict) --
The dimension-based condition that specifies how to filter the data based on dimension values.
Dimension (string) --
The name of the dimension to filter by.
Comparison (string) --
The comparison operator to use for the filter.
Values (list) --
The list of values to match against the specified dimension. For 'equals' comparison, only the first value is used. For 'in' comparison, any matching value will satisfy the condition.
(string) --
integer
The maximum number of data points to return. Valid range is 1 to 100,000. Use with NextToken for pagination of large result sets.
string
The token for the next page of results. Use this value in a subsequent call to retrieve additional data points.
boolean
Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.
dict
Response Syntax
{
'MetricDataResults': [
{
'Dimension': {
'ResourceRegion': 'string',
'AvailabilityZoneId': 'string',
'AccountId': 'string',
'AccountName': 'string',
'InstanceFamily': 'string',
'InstanceType': 'string',
'InstancePlatform': 'string',
'ReservationArn': 'string',
'ReservationId': 'string',
'ReservationType': 'capacity-block'|'odcr',
'ReservationCreateTimestamp': datetime(2015, 1, 1),
'ReservationStartTimestamp': datetime(2015, 1, 1),
'ReservationEndTimestamp': datetime(2015, 1, 1),
'ReservationEndDateType': 'limited'|'unlimited',
'Tenancy': 'default'|'dedicated',
'ReservationState': 'active'|'expired'|'cancelled'|'scheduled'|'pending'|'failed'|'delayed'|'unsupported'|'payment-pending'|'payment-failed'|'retired',
'ReservationInstanceMatchCriteria': 'string',
'ReservationUnusedFinancialOwner': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
'Timestamp': datetime(2015, 1, 1),
'MetricValues': [
{
'Metric': 'reservation-total-capacity-hrs-vcpu'|'reservation-total-capacity-hrs-inst'|'reservation-max-size-vcpu'|'reservation-max-size-inst'|'reservation-min-size-vcpu'|'reservation-min-size-inst'|'reservation-unused-total-capacity-hrs-vcpu'|'reservation-unused-total-capacity-hrs-inst'|'reservation-unused-total-estimated-cost'|'reservation-max-unused-size-vcpu'|'reservation-max-unused-size-inst'|'reservation-min-unused-size-vcpu'|'reservation-min-unused-size-inst'|'reservation-max-utilization'|'reservation-min-utilization'|'reservation-avg-utilization-vcpu'|'reservation-avg-utilization-inst'|'reservation-total-count'|'reservation-total-estimated-cost'|'reservation-avg-future-size-vcpu'|'reservation-avg-future-size-inst'|'reservation-min-future-size-vcpu'|'reservation-min-future-size-inst'|'reservation-max-future-size-vcpu'|'reservation-max-future-size-inst'|'reservation-avg-committed-size-vcpu'|'reservation-avg-committed-size-inst'|'reservation-max-committed-size-vcpu'|'reservation-max-committed-size-inst'|'reservation-min-committed-size-vcpu'|'reservation-min-committed-size-inst'|'reserved-total-usage-hrs-vcpu'|'reserved-total-usage-hrs-inst'|'reserved-total-estimated-cost'|'unreserved-total-usage-hrs-vcpu'|'unreserved-total-usage-hrs-inst'|'unreserved-total-estimated-cost'|'spot-total-usage-hrs-vcpu'|'spot-total-usage-hrs-inst'|'spot-total-estimated-cost'|'spot-avg-run-time-before-interruption-inst'|'spot-max-run-time-before-interruption-inst'|'spot-min-run-time-before-interruption-inst'|'spot-total-interruptions-inst'|'spot-total-interruptions-vcpu'|'spot-total-count-inst'|'spot-total-count-vcpu'|'spot-interruption-rate-inst'|'spot-interruption-rate-vcpu'|'capacity-total-requested-vcpu'|'capacity-total-fulfilled-vcpu'|'spot-capacity-total-requested-vcpu'|'spot-capacity-total-fulfilled-vcpu'|'capacity-request-fulfillment-rate'|'avg-inst-az-count-per-requested-vcpu'|'inst-az-fulfillment-rate'|'spot-capacity-request-fulfillment-rate'|'spot-avg-inst-az-count-per-requested-vcpu'|'spot-inst-az-fulfillment-rate',
'Value': 123.0
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
MetricDataResults (list) --
The metric data points returned by the query. Each result contains dimension values, timestamp, and metric values with their associated statistics.
(dict) --
Contains a single data point from a capacity metrics query, including the dimension values, timestamp, and metric values for that specific combination.
Dimension (dict) --
The dimension values that identify this specific data point, such as account ID, region, and instance family.
ResourceRegion (string) --
The Amazon Web Services Region where the capacity resource is located.
AvailabilityZoneId (string) --
The unique identifier of the Availability Zone where the capacity resource is located.
AccountId (string) --
The Amazon Web Services account ID that owns the capacity resource.
AccountName (string) --
The name of the Amazon Web Services account that owns the capacity resource. This dimension is only available when Organizations access is enabled for Capacity Manager.
InstanceFamily (string) --
The EC2 instance family of the capacity resource.
InstanceType (string) --
The specific EC2 instance type of the capacity resource.
InstancePlatform (string) --
The platform or operating system of the instance.
ReservationArn (string) --
The Amazon Resource Name (ARN) of the capacity reservation. This provides a unique identifier that can be used across Amazon Web Services services to reference the specific reservation.
ReservationId (string) --
The unique identifier of the capacity reservation.
ReservationType (string) --
The type of capacity reservation.
ReservationCreateTimestamp (datetime) --
The timestamp when the capacity reservation was originally created, in milliseconds since epoch. This differs from the start timestamp as reservations can be created before they become active.
ReservationStartTimestamp (datetime) --
The timestamp when the capacity reservation becomes active and available for use, in milliseconds since epoch. This is when the reservation begins providing capacity.
ReservationEndTimestamp (datetime) --
The timestamp when the capacity reservation expires and is no longer available, in milliseconds since epoch. After this time, the reservation will not provide any capacity.
ReservationEndDateType (string) --
The type of end date for the capacity reservation. This indicates whether the reservation has a fixed end date, is open-ended, or follows a specific termination pattern.
Tenancy (string) --
The tenancy of the EC2 instances associated with this capacity dimension. Valid values are 'default' for shared tenancy, 'dedicated' for dedicated instances, or 'host' for dedicated hosts.
ReservationState (string) --
The current state of the capacity reservation.
ReservationInstanceMatchCriteria (string) --
The instance matching criteria for the capacity reservation, determining how instances are matched to the reservation.
ReservationUnusedFinancialOwner (string) --
The Amazon Web Services account ID that is financially responsible for unused capacity reservation costs.
Tags (list) --
The tags associated with the capacity resource, represented as key-value pairs. Only tags that have been activated for monitoring via UpdateCapacityManagerMonitoredTagKeys are included.
(dict) --
A key-value pair representing a tag associated with a capacity resource in Capacity Manager.
Key (string) --
The tag key.
Value (string) --
The tag value.
Timestamp (datetime) --
The timestamp for this data point, indicating when the capacity usage occurred.
MetricValues (list) --
The metric values and statistics for this data point, containing the actual capacity usage numbers.
(dict) --
Represents a single metric value with its associated statistic, such as the sum or average of unused capacity hours.
Metric (string) --
The name of the metric.
Value (float) --
The numerical value of the metric for the specified statistic and time period.
NextToken (string) --
The token to use to retrieve the next page of results. This value is null when there are no more results to return.
{'MetricNames': {'avg-inst-az-count-per-requested-vcpu',
'capacity-request-fulfillment-rate',
'capacity-total-fulfilled-vcpu',
'capacity-total-requested-vcpu',
'inst-az-fulfillment-rate',
'spot-avg-inst-az-count-per-requested-vcpu',
'spot-capacity-request-fulfillment-rate',
'spot-capacity-total-fulfilled-vcpu',
'spot-capacity-total-requested-vcpu',
'spot-inst-az-fulfillment-rate'}}
Retrieves the available dimension values for capacity metrics within a specified time range. This is useful for discovering what accounts, regions, instance families, and other dimensions have data available for filtering and grouping.
See also: AWS API Documentation
Request Syntax
client.get_capacity_manager_metric_dimensions(
GroupBy=[
'resource-region'|'availability-zone-id'|'account-id'|'account-name'|'instance-family'|'instance-type'|'instance-platform'|'reservation-arn'|'reservation-id'|'reservation-type'|'reservation-create-timestamp'|'reservation-start-timestamp'|'reservation-end-timestamp'|'reservation-end-date-type'|'tenancy'|'reservation-state'|'reservation-instance-match-criteria'|'reservation-unused-financial-owner',
],
FilterBy=[
{
'DimensionCondition': {
'Dimension': 'resource-region'|'availability-zone-id'|'account-id'|'account-name'|'instance-family'|'instance-type'|'instance-platform'|'reservation-arn'|'reservation-id'|'reservation-type'|'reservation-create-timestamp'|'reservation-start-timestamp'|'reservation-end-timestamp'|'reservation-end-date-type'|'tenancy'|'reservation-state'|'reservation-instance-match-criteria'|'reservation-unused-financial-owner',
'Comparison': 'equals'|'in',
'Values': [
'string',
]
}
},
],
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
MetricNames=[
'reservation-total-capacity-hrs-vcpu'|'reservation-total-capacity-hrs-inst'|'reservation-max-size-vcpu'|'reservation-max-size-inst'|'reservation-min-size-vcpu'|'reservation-min-size-inst'|'reservation-unused-total-capacity-hrs-vcpu'|'reservation-unused-total-capacity-hrs-inst'|'reservation-unused-total-estimated-cost'|'reservation-max-unused-size-vcpu'|'reservation-max-unused-size-inst'|'reservation-min-unused-size-vcpu'|'reservation-min-unused-size-inst'|'reservation-max-utilization'|'reservation-min-utilization'|'reservation-avg-utilization-vcpu'|'reservation-avg-utilization-inst'|'reservation-total-count'|'reservation-total-estimated-cost'|'reservation-avg-future-size-vcpu'|'reservation-avg-future-size-inst'|'reservation-min-future-size-vcpu'|'reservation-min-future-size-inst'|'reservation-max-future-size-vcpu'|'reservation-max-future-size-inst'|'reservation-avg-committed-size-vcpu'|'reservation-avg-committed-size-inst'|'reservation-max-committed-size-vcpu'|'reservation-max-committed-size-inst'|'reservation-min-committed-size-vcpu'|'reservation-min-committed-size-inst'|'reserved-total-usage-hrs-vcpu'|'reserved-total-usage-hrs-inst'|'reserved-total-estimated-cost'|'unreserved-total-usage-hrs-vcpu'|'unreserved-total-usage-hrs-inst'|'unreserved-total-estimated-cost'|'spot-total-usage-hrs-vcpu'|'spot-total-usage-hrs-inst'|'spot-total-estimated-cost'|'spot-avg-run-time-before-interruption-inst'|'spot-max-run-time-before-interruption-inst'|'spot-min-run-time-before-interruption-inst'|'spot-total-interruptions-inst'|'spot-total-interruptions-vcpu'|'spot-total-count-inst'|'spot-total-count-vcpu'|'spot-interruption-rate-inst'|'spot-interruption-rate-vcpu'|'capacity-total-requested-vcpu'|'capacity-total-fulfilled-vcpu'|'spot-capacity-total-requested-vcpu'|'spot-capacity-total-fulfilled-vcpu'|'capacity-request-fulfillment-rate'|'avg-inst-az-count-per-requested-vcpu'|'inst-az-fulfillment-rate'|'spot-capacity-request-fulfillment-rate'|'spot-avg-inst-az-count-per-requested-vcpu'|'spot-inst-az-fulfillment-rate',
],
MaxResults=123,
NextToken='string',
DryRun=True|False
)
list
[REQUIRED]
The dimensions to group by when retrieving available dimension values. This determines which dimension combinations are returned. Required parameter.
(string) --
list
Conditions to filter which dimension values are returned. Each filter specifies a dimension, comparison operator, and values to match against.
(dict) --
Represents a filter condition for Capacity Manager queries. Contains dimension-based filtering criteria used to narrow down metric data and dimension results.
DimensionCondition (dict) --
The dimension-based condition that specifies how to filter the data based on dimension values.
Dimension (string) --
The name of the dimension to filter by.
Comparison (string) --
The comparison operator to use for the filter.
Values (list) --
The list of values to match against the specified dimension. For 'equals' comparison, only the first value is used. For 'in' comparison, any matching value will satisfy the condition.
(string) --
datetime
[REQUIRED]
The start time for the dimension query, in ISO 8601 format. Only dimensions with data in this time range will be returned.
datetime
[REQUIRED]
The end time for the dimension query, in ISO 8601 format. Only dimensions with data in this time range will be returned.
list
[REQUIRED]
The metric names to use as an additional filter when retrieving dimensions. Only dimensions that have data for these metrics will be returned. Required parameter with maximum size of 1 for v1.
(string) --
integer
The maximum number of dimension combinations to return. Valid range is 1 to 1000. Use with NextToken for pagination.
string
The token for the next page of results. Use this value in a subsequent call to retrieve additional dimension values.
boolean
Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.
dict
Response Syntax
{
'MetricDimensionResults': [
{
'ResourceRegion': 'string',
'AvailabilityZoneId': 'string',
'AccountId': 'string',
'AccountName': 'string',
'InstanceFamily': 'string',
'InstanceType': 'string',
'InstancePlatform': 'string',
'ReservationArn': 'string',
'ReservationId': 'string',
'ReservationType': 'capacity-block'|'odcr',
'ReservationCreateTimestamp': datetime(2015, 1, 1),
'ReservationStartTimestamp': datetime(2015, 1, 1),
'ReservationEndTimestamp': datetime(2015, 1, 1),
'ReservationEndDateType': 'limited'|'unlimited',
'Tenancy': 'default'|'dedicated',
'ReservationState': 'active'|'expired'|'cancelled'|'scheduled'|'pending'|'failed'|'delayed'|'unsupported'|'payment-pending'|'payment-failed'|'retired',
'ReservationInstanceMatchCriteria': 'string',
'ReservationUnusedFinancialOwner': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
MetricDimensionResults (list) --
The available dimension combinations that have data within the specified time range and filters.
(dict) --
Represents dimension values for capacity metrics, including resource identifiers, geographic information, and reservation details used for grouping and filtering capacity data.
ResourceRegion (string) --
The Amazon Web Services Region where the capacity resource is located.
AvailabilityZoneId (string) --
The unique identifier of the Availability Zone where the capacity resource is located.
AccountId (string) --
The Amazon Web Services account ID that owns the capacity resource.
AccountName (string) --
The name of the Amazon Web Services account that owns the capacity resource. This dimension is only available when Organizations access is enabled for Capacity Manager.
InstanceFamily (string) --
The EC2 instance family of the capacity resource.
InstanceType (string) --
The specific EC2 instance type of the capacity resource.
InstancePlatform (string) --
The platform or operating system of the instance.
ReservationArn (string) --
The Amazon Resource Name (ARN) of the capacity reservation. This provides a unique identifier that can be used across Amazon Web Services services to reference the specific reservation.
ReservationId (string) --
The unique identifier of the capacity reservation.
ReservationType (string) --
The type of capacity reservation.
ReservationCreateTimestamp (datetime) --
The timestamp when the capacity reservation was originally created, in milliseconds since epoch. This differs from the start timestamp as reservations can be created before they become active.
ReservationStartTimestamp (datetime) --
The timestamp when the capacity reservation becomes active and available for use, in milliseconds since epoch. This is when the reservation begins providing capacity.
ReservationEndTimestamp (datetime) --
The timestamp when the capacity reservation expires and is no longer available, in milliseconds since epoch. After this time, the reservation will not provide any capacity.
ReservationEndDateType (string) --
The type of end date for the capacity reservation. This indicates whether the reservation has a fixed end date, is open-ended, or follows a specific termination pattern.
Tenancy (string) --
The tenancy of the EC2 instances associated with this capacity dimension. Valid values are 'default' for shared tenancy, 'dedicated' for dedicated instances, or 'host' for dedicated hosts.
ReservationState (string) --
The current state of the capacity reservation.
ReservationInstanceMatchCriteria (string) --
The instance matching criteria for the capacity reservation, determining how instances are matched to the reservation.
ReservationUnusedFinancialOwner (string) --
The Amazon Web Services account ID that is financially responsible for unused capacity reservation costs.
Tags (list) --
The tags associated with the capacity resource, represented as key-value pairs. Only tags that have been activated for monitoring via UpdateCapacityManagerMonitoredTagKeys are included.
(dict) --
A key-value pair representing a tag associated with a capacity resource in Capacity Manager.
Key (string) --
The tag key.
Value (string) --
The tag value.
NextToken (string) --
The token to use to retrieve the next page of results. This value is null when there are no more results to return.