Retrieves the Savings Plans covered for your account. This enables you to see how much of your cost is covered by a Savings Plan. An organization’s management account can see the coverage of the associated member accounts. This supports dimensions, Cost Categories, and nested expressions. For any time period, you can filter data for Savings Plans usage with the following dimensions:
LINKED_ACCOUNT
REGION
SERVICE
INSTANCE_FAMILY
To determine valid values for a dimension, use the GetDimensionValues
operation.
See also: AWS API Documentation
See ‘aws help’ for descriptions of global parameters.
get-savings-plans-coverage
--time-period <value>
[--group-by <value>]
[--granularity <value>]
[--filter <value>]
[--metrics <value>]
[--next-token <value>]
[--max-results <value>]
[--sort-by <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
--time-period
(structure)
The time period that you want the usage and costs for. The
Start
date must be within 13 months. TheEnd
date must be after theStart
date, and before the current date. Future dates can’t be used as anEnd
date.Start -> (string)
The beginning of the time period. The start date is inclusive. For example, if
start
is2017-01-01
, Amazon Web Services retrieves cost and usage data starting at2017-01-01
up to the end date. The start date must be equal to or no later than the current date to avoid a validation error.End -> (string)
The end of the time period. The end date is exclusive. For example, if
end
is2017-05-01
, Amazon Web Services retrieves cost and usage data from the start date up to, but not including,2017-05-01
.
Shorthand Syntax:
Start=string,End=string
JSON Syntax:
{
"Start": "string",
"End": "string"
}
--group-by
(list)
You can group the data using the attributes
INSTANCE_FAMILY
,REGION
, orSERVICE
.(structure)
Represents a group when you specify a group by criteria or in the response to a query with a specific grouping.
Type -> (string)
The string that represents the type of group.
Key -> (string)
The string that represents a key for a specified group.
Shorthand Syntax:
Type=string,Key=string ...
JSON Syntax:
[
{
"Type": "DIMENSION"|"TAG"|"COST_CATEGORY",
"Key": "string"
}
...
]
--granularity
(string)
The granularity of the Amazon Web Services cost data for your Savings Plans.
Granularity
can’t be set ifGroupBy
is set.The
GetSavingsPlansCoverage
operation supports onlyDAILY
andMONTHLY
granularities.Possible values:
DAILY
MONTHLY
HOURLY
--filter
(structure)
Filters Savings Plans coverage data by dimensions. You can filter data for Savings Plans usage with the following dimensions:
LINKED_ACCOUNT
REGION
SERVICE
INSTANCE_FAMILY
GetSavingsPlansCoverage
uses the same Expression object as the other operations, but onlyAND
is supported among each dimension. If there are multiple values for a dimension, they are OR’d together.Cost category is also supported.
Or -> (list)
Return results that match either
Dimension
object.(structure)
Use
Expression
to filter by cost or by usage. There are two patterns:
Simple dimension values - You can set the dimension name and values for the filters that you plan to use. For example, you can filter for
REGION==us-east-1 OR REGION==us-west-1
. ForGetRightsizingRecommendation
, the Region is a full name (for example,REGION==US East (N. Virginia)
. TheExpression
example is as follows:{ "Dimensions": { "Key": "REGION", "Values": [ "us-east-1", “us-west-1” ] } }
The list of dimension values are OR’d together to retrieve cost or usage data. You can createExpression
andDimensionValues
objects using eitherwith*
methods orset*
methods in multiple lines.Compound dimension values with logical operations - You can use multiple
Expression
types and the logical operatorsAND/OR/NOT
to create a list of one or moreExpression
objects. By doing this, you can filter on more advanced options. For example, you can filter on((REGION == us-east-1 OR REGION == us-west-1) OR (TAG.Type == Type1)) AND (USAGE_TYPE != DataTransfer)
. TheExpression
for that is as follows:{ "And": [ {"Or": [ {"Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ] }}, {"Tags": { "Key": "TagName", "Values": ["Value1"] } } ]}, {"Not": {"Dimensions": { "Key": "USAGE_TYPE", "Values": ["DataTransfer"] }}} ] }
Note
Because each
Expression
can have only one operator, the service returns an error if more than one is specified. The following example shows anExpression
object that creates an error.
{ "And": [ ... ], "DimensionValues": { "Dimension": "USAGE_TYPE", "Values": [ "DataTransfer" ] } }
Note
For the
GetRightsizingRecommendation
action, a combination of OR and NOT isn’t supported. OR isn’t supported between different dimensions, or dimensions and tags. NOT operators aren’t supported. Dimensions are also limited toLINKED_ACCOUNT
,REGION
, orRIGHTSIZING_TYPE
.For the
GetReservationPurchaseRecommendation
action, only NOT is supported. AND and OR aren’t supported. Dimensions are limited toLINKED_ACCOUNT
.Or -> (list)
Return results that match either
Dimension
object.( … recursive … )
And -> (list)
Return results that match both
Dimension
objects.( … recursive … )
( … recursive … )Dimensions -> (structure)
The specific
Dimension
to use forExpression
.Key -> (string)
The names of the metadata types that you can use to filter and group your results. For example,
AZ
returns a list of Availability Zones.Values -> (list)
The metadata values that you can use to filter and group your results. You can use
GetDimensionValues
to find specific values.(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
Tags -> (structure)
The specific
Tag
to use forExpression
.Key -> (string)
The key for the tag.
Values -> (list)
The specific value of the tag.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
CostCategories -> (structure)
The filter that’s based on
CostCategory
values.Key -> (string)
The unique name of the Cost Category.
Values -> (list)
The specific value of the Cost Category.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results. MatchOptions is only applicable for actions related to cost category. The default values for
MatchOptions
isEQUALS
andCASE_SENSITIVE
.(string)
And -> (list)
Return results that match both
Dimension
objects.(structure)
Use
Expression
to filter by cost or by usage. There are two patterns:
Simple dimension values - You can set the dimension name and values for the filters that you plan to use. For example, you can filter for
REGION==us-east-1 OR REGION==us-west-1
. ForGetRightsizingRecommendation
, the Region is a full name (for example,REGION==US East (N. Virginia)
. TheExpression
example is as follows:{ "Dimensions": { "Key": "REGION", "Values": [ "us-east-1", “us-west-1” ] } }
The list of dimension values are OR’d together to retrieve cost or usage data. You can createExpression
andDimensionValues
objects using eitherwith*
methods orset*
methods in multiple lines.Compound dimension values with logical operations - You can use multiple
Expression
types and the logical operatorsAND/OR/NOT
to create a list of one or moreExpression
objects. By doing this, you can filter on more advanced options. For example, you can filter on((REGION == us-east-1 OR REGION == us-west-1) OR (TAG.Type == Type1)) AND (USAGE_TYPE != DataTransfer)
. TheExpression
for that is as follows:{ "And": [ {"Or": [ {"Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ] }}, {"Tags": { "Key": "TagName", "Values": ["Value1"] } } ]}, {"Not": {"Dimensions": { "Key": "USAGE_TYPE", "Values": ["DataTransfer"] }}} ] }
Note
Because each
Expression
can have only one operator, the service returns an error if more than one is specified. The following example shows anExpression
object that creates an error.
{ "And": [ ... ], "DimensionValues": { "Dimension": "USAGE_TYPE", "Values": [ "DataTransfer" ] } }
Note
For the
GetRightsizingRecommendation
action, a combination of OR and NOT isn’t supported. OR isn’t supported between different dimensions, or dimensions and tags. NOT operators aren’t supported. Dimensions are also limited toLINKED_ACCOUNT
,REGION
, orRIGHTSIZING_TYPE
.For the
GetReservationPurchaseRecommendation
action, only NOT is supported. AND and OR aren’t supported. Dimensions are limited toLINKED_ACCOUNT
.Or -> (list)
Return results that match either
Dimension
object.( … recursive … )
And -> (list)
Return results that match both
Dimension
objects.( … recursive … )
( … recursive … )Dimensions -> (structure)
The specific
Dimension
to use forExpression
.Key -> (string)
The names of the metadata types that you can use to filter and group your results. For example,
AZ
returns a list of Availability Zones.Values -> (list)
The metadata values that you can use to filter and group your results. You can use
GetDimensionValues
to find specific values.(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
Tags -> (structure)
The specific
Tag
to use forExpression
.Key -> (string)
The key for the tag.
Values -> (list)
The specific value of the tag.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
CostCategories -> (structure)
The filter that’s based on
CostCategory
values.Key -> (string)
The unique name of the Cost Category.
Values -> (list)
The specific value of the Cost Category.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results. MatchOptions is only applicable for actions related to cost category. The default values for
MatchOptions
isEQUALS
andCASE_SENSITIVE
.(string)
Not -> (structure)
Return results that don’t match a
Dimension
object.Or -> (list)
Return results that match either
Dimension
object.( … recursive … )
And -> (list)
Return results that match both
Dimension
objects.( … recursive … )
( … recursive … )Dimensions -> (structure)
The specific
Dimension
to use forExpression
.Key -> (string)
The names of the metadata types that you can use to filter and group your results. For example,
AZ
returns a list of Availability Zones.Values -> (list)
The metadata values that you can use to filter and group your results. You can use
GetDimensionValues
to find specific values.(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
Tags -> (structure)
The specific
Tag
to use forExpression
.Key -> (string)
The key for the tag.
Values -> (list)
The specific value of the tag.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
CostCategories -> (structure)
The filter that’s based on
CostCategory
values.Key -> (string)
The unique name of the Cost Category.
Values -> (list)
The specific value of the Cost Category.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results. MatchOptions is only applicable for actions related to cost category. The default values for
MatchOptions
isEQUALS
andCASE_SENSITIVE
.(string)
Dimensions -> (structure)
The specific
Dimension
to use forExpression
.Key -> (string)
The names of the metadata types that you can use to filter and group your results. For example,
AZ
returns a list of Availability Zones.Values -> (list)
The metadata values that you can use to filter and group your results. You can use
GetDimensionValues
to find specific values.(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
Tags -> (structure)
The specific
Tag
to use forExpression
.Key -> (string)
The key for the tag.
Values -> (list)
The specific value of the tag.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results.
MatchOptions
is only applicable for actions related to Cost Category. The default values forMatchOptions
areEQUALS
andCASE_SENSITIVE
.(string)
CostCategories -> (structure)
The filter that’s based on
CostCategory
values.Key -> (string)
The unique name of the Cost Category.
Values -> (list)
The specific value of the Cost Category.
(string)
MatchOptions -> (list)
The match options that you can use to filter your results. MatchOptions is only applicable for actions related to cost category. The default values for
MatchOptions
isEQUALS
andCASE_SENSITIVE
.(string)
JSON Syntax:
{
"Or": [
{
"Or": [
{ ... recursive ... }
...
],
"And": [
{ ... recursive ... }
...
],
"Not": { ... recursive ... },
"Dimensions": {
"Key": "AZ"|"INSTANCE_TYPE"|"LINKED_ACCOUNT"|"LINKED_ACCOUNT_NAME"|"OPERATION"|"PURCHASE_TYPE"|"REGION"|"SERVICE"|"SERVICE_CODE"|"USAGE_TYPE"|"USAGE_TYPE_GROUP"|"RECORD_TYPE"|"OPERATING_SYSTEM"|"TENANCY"|"SCOPE"|"PLATFORM"|"SUBSCRIPTION_ID"|"LEGAL_ENTITY_NAME"|"DEPLOYMENT_OPTION"|"DATABASE_ENGINE"|"CACHE_ENGINE"|"INSTANCE_TYPE_FAMILY"|"BILLING_ENTITY"|"RESERVATION_ID"|"RESOURCE_ID"|"RIGHTSIZING_TYPE"|"SAVINGS_PLANS_TYPE"|"SAVINGS_PLAN_ARN"|"PAYMENT_OPTION"|"AGREEMENT_END_DATE_TIME_AFTER"|"AGREEMENT_END_DATE_TIME_BEFORE"|"INVOICING_ENTITY",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"Tags": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"CostCategories": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
}
}
...
],
"And": [
{
"Or": [
{ ... recursive ... }
...
],
"And": [
{ ... recursive ... }
...
],
"Not": { ... recursive ... },
"Dimensions": {
"Key": "AZ"|"INSTANCE_TYPE"|"LINKED_ACCOUNT"|"LINKED_ACCOUNT_NAME"|"OPERATION"|"PURCHASE_TYPE"|"REGION"|"SERVICE"|"SERVICE_CODE"|"USAGE_TYPE"|"USAGE_TYPE_GROUP"|"RECORD_TYPE"|"OPERATING_SYSTEM"|"TENANCY"|"SCOPE"|"PLATFORM"|"SUBSCRIPTION_ID"|"LEGAL_ENTITY_NAME"|"DEPLOYMENT_OPTION"|"DATABASE_ENGINE"|"CACHE_ENGINE"|"INSTANCE_TYPE_FAMILY"|"BILLING_ENTITY"|"RESERVATION_ID"|"RESOURCE_ID"|"RIGHTSIZING_TYPE"|"SAVINGS_PLANS_TYPE"|"SAVINGS_PLAN_ARN"|"PAYMENT_OPTION"|"AGREEMENT_END_DATE_TIME_AFTER"|"AGREEMENT_END_DATE_TIME_BEFORE"|"INVOICING_ENTITY",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"Tags": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"CostCategories": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
}
}
...
],
"Not": {
"Or": [
{ ... recursive ... }
...
],
"And": [
{ ... recursive ... }
...
],
"Not": { ... recursive ... },
"Dimensions": {
"Key": "AZ"|"INSTANCE_TYPE"|"LINKED_ACCOUNT"|"LINKED_ACCOUNT_NAME"|"OPERATION"|"PURCHASE_TYPE"|"REGION"|"SERVICE"|"SERVICE_CODE"|"USAGE_TYPE"|"USAGE_TYPE_GROUP"|"RECORD_TYPE"|"OPERATING_SYSTEM"|"TENANCY"|"SCOPE"|"PLATFORM"|"SUBSCRIPTION_ID"|"LEGAL_ENTITY_NAME"|"DEPLOYMENT_OPTION"|"DATABASE_ENGINE"|"CACHE_ENGINE"|"INSTANCE_TYPE_FAMILY"|"BILLING_ENTITY"|"RESERVATION_ID"|"RESOURCE_ID"|"RIGHTSIZING_TYPE"|"SAVINGS_PLANS_TYPE"|"SAVINGS_PLAN_ARN"|"PAYMENT_OPTION"|"AGREEMENT_END_DATE_TIME_AFTER"|"AGREEMENT_END_DATE_TIME_BEFORE"|"INVOICING_ENTITY",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"Tags": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"CostCategories": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
}
},
"Dimensions": {
"Key": "AZ"|"INSTANCE_TYPE"|"LINKED_ACCOUNT"|"LINKED_ACCOUNT_NAME"|"OPERATION"|"PURCHASE_TYPE"|"REGION"|"SERVICE"|"SERVICE_CODE"|"USAGE_TYPE"|"USAGE_TYPE_GROUP"|"RECORD_TYPE"|"OPERATING_SYSTEM"|"TENANCY"|"SCOPE"|"PLATFORM"|"SUBSCRIPTION_ID"|"LEGAL_ENTITY_NAME"|"DEPLOYMENT_OPTION"|"DATABASE_ENGINE"|"CACHE_ENGINE"|"INSTANCE_TYPE_FAMILY"|"BILLING_ENTITY"|"RESERVATION_ID"|"RESOURCE_ID"|"RIGHTSIZING_TYPE"|"SAVINGS_PLANS_TYPE"|"SAVINGS_PLAN_ARN"|"PAYMENT_OPTION"|"AGREEMENT_END_DATE_TIME_AFTER"|"AGREEMENT_END_DATE_TIME_BEFORE"|"INVOICING_ENTITY",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"Tags": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
},
"CostCategories": {
"Key": "string",
"Values": ["string", ...],
"MatchOptions": ["EQUALS"|"ABSENT"|"STARTS_WITH"|"ENDS_WITH"|"CONTAINS"|"CASE_SENSITIVE"|"CASE_INSENSITIVE", ...]
}
}
--metrics
(list)
The measurement that you want your Savings Plans coverage reported in. The only valid value is
SpendCoveredBySavingsPlans
.(string)
Syntax:
"string" "string" ...
--next-token
(string)
The token to retrieve the next set of results. Amazon Web Services provides the token when the response from a previous call has more results than the maximum page size.
--max-results
(integer)
The number of items to be returned in a response. The default is
20
, with a minimum value of1
.
--sort-by
(structure)
The value by which you want to sort the data.
The following values are supported for
Key
:
SpendCoveredBySavingsPlan
OnDemandCost
CoveragePercentage
TotalCost
InstanceFamily
Region
Service
Supported values for
SortOrder
areASCENDING
orDESCENDING
.Key -> (string)
The key that’s used to sort the data.
SortOrder -> (string)
The order that’s used to sort the data.
Shorthand Syntax:
Key=string,SortOrder=string
JSON Syntax:
{
"Key": "string",
"SortOrder": "ASCENDING"|"DESCENDING"
}
--cli-input-json
| --cli-input-yaml
(string)
Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton
. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml
.
--generate-cli-skeleton
(string)
Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input
, prints a sample input JSON that can be used as an argument for --cli-input-json
. Similarly, if provided yaml-input
it will print a sample input YAML that can be used with --cli-input-yaml
. If provided with the value output
, it validates the command inputs and returns a sample output JSON for that command.
See ‘aws help’ for descriptions of global parameters.
SavingsPlansCoverages -> (list)
The amount of spend that your Savings Plans covered.
(structure)
The amount of Savings Plans eligible usage that is covered by Savings Plans. All calculations consider the On-Demand equivalent of your Savings Plans usage.
Attributes -> (map)
The attribute that applies to a specific
Dimension
.key -> (string)
value -> (string)
Coverage -> (structure)
The amount of Savings Plans eligible usage that the Savings Plans covered.
SpendCoveredBySavingsPlans -> (string)
The amount of your Amazon Web Services usage that is covered by a Savings Plans.
OnDemandCost -> (string)
The cost of your Amazon Web Services usage at the public On-Demand rate.
TotalCost -> (string)
The total cost of your Amazon Web Services usage, regardless of your purchase option.
CoveragePercentage -> (string)
The percentage of your existing Savings Plans covered usage, divided by all of your eligible Savings Plans usage in an account (or set of accounts).
TimePeriod -> (structure)
The time period of the request.
Start -> (string)
The beginning of the time period. The start date is inclusive. For example, if
start
is2017-01-01
, Amazon Web Services retrieves cost and usage data starting at2017-01-01
up to the end date. The start date must be equal to or no later than the current date to avoid a validation error.End -> (string)
The end of the time period. The end date is exclusive. For example, if
end
is2017-05-01
, Amazon Web Services retrieves cost and usage data from the start date up to, but not including,2017-05-01
.
NextToken -> (string)
The token to retrieve the next set of results. Amazon Web Services provides the token when the response from a previous call has more results than the maximum page size.