GetDimensionValues
Retrieves all available filter values for a specified filter over a period of time. You can search the dimension values for an arbitrary string.
Request Syntax
{
"BillingViewArn": "string",
"Context": "string",
"Dimension": "string",
"DimensionKey": "string",
"Filter": {
"And": [
"Expression"
],
"CostCategories": {
"Key": "string",
"MatchOptions": [ "string" ],
"Values": [ "string" ]
},
"Dimensions": {
"Key": "string",
"MatchOptions": [ "string" ],
"Values": [ "string" ]
},
"Not": "Expression",
"Or": [
"Expression"
],
"ProductAttributes": {
"Key": "string",
"MatchOptions": [ "string" ],
"Values": [ "string" ]
},
"Tags": {
"Key": "string",
"MatchOptions": [ "string" ],
"Values": [ "string" ]
}
},
"MaxResults": number,
"NextPageToken": "string",
"SearchString": "string",
"SortBy": [
{
"Key": "string",
"SortOrder": "string"
}
],
"TimePeriod": {
"End": "string",
"Start": "string"
}
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- BillingViewArn
-
The Amazon Resource Name (ARN) that uniquely identifies a specific billing view. The ARN is used to specify which particular billing view you want to interact with or retrieve information from when making API calls related to AWS Billing and Cost Management features. The BillingViewArn can be retrieved by calling the ListBillingViews API.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Pattern:
^arn:aws[a-z-]*:(billing)::[0-9]{12}:billingview/[-a-zA-Z0-9/:_+=.-@]{1,43}$Required: No
- Context
-
The context for the call to
GetDimensionValues. This can beCOST_AND_USAGE,RESERVATIONS, orSAVINGS_PLANS. The default value isCOST_AND_USAGE. If the context is set toRESERVATIONS, the resulting dimension values can be used in theGetReservationUtilizationoperation.GetReservationCoveragefilters match cost and usage data, so useCOST_AND_USAGEvalues for them. If the context is set toSAVINGS_PLANS, the resulting dimension values can be used in theGetSavingsPlansUtilizationandGetSavingsPlansUtilizationDetailsoperations. If the context is set toCOST_AND_USAGE, the resulting dimension values can be used in theGetCostAndUsageoperation.If you set the context to
COST_AND_USAGE, you can use the following dimensions for searching:-
AZ - The Availability Zone. An example is
us-east-1a. -
BILLING_ENTITY - The AWS seller that your account is with. Possible values are the following:
- AWS(Amazon Web Services): The entity that sells AWS services.
- AISPL (Amazon Internet Services Pvt. Ltd.): The local Indian entity that's an acting reseller for AWS services in India.
- AWS Marketplace: The entity that supports the sale of solutions that are built on AWS by third-party software providers.
-
CACHE_ENGINE - The Amazon ElastiCache engine. Examples are
Redis,Valkey, andMemcached. -
DEPLOYMENT_OPTION - The scope of Amazon Relational Database Service deployments. Examples are
Single-AZandMulti-AZ. -
DATABASE_ENGINE - The Amazon Relational Database Service database engine. Examples are
Aurora MySQL,Aurora PostgreSQL, andMySQL. -
INSTANCE_TYPE - The type of Amazon EC2 instance. An example is
m4.xlarge. -
INSTANCE_TYPE_FAMILY - A family of instance types optimized to fit different use cases. The value is the family code, such as
m5orc6gfor Amazon EC2. The casing of the code follows each service's product catalog, for exampleR6Gfor Amazon Relational Database Service. -
INVOICING_ENTITY - The name of the entity that issues the AWS invoice.
-
LEGAL_ENTITY_NAME - The name of the organization that sells you AWS services, such as Amazon Web Services.
-
LINKED_ACCOUNT - The description in the attribute map that includes the full name of the member account. The value field contains the AWS ID of the member account.
-
OPERATING_SYSTEM - The operating system. Examples are
Linux/UNIX,Windows (Amazon VPC), andRed Hat Enterprise Linux. -
OPERATION - The action performed. Examples include
RunInstanceandCreateBucket. -
PLATFORM - The operating system or platform of the usage. Examples are
Linux/UNIX,Windows (Amazon VPC), andRed Hat Enterprise Linux. -
PRODUCT_ATTRIBUTE - The product attributes of supported services, such as the model provider or the model for Amazon Bedrock.
-
PURCHASE_TYPE - The reservation type of the purchase that this usage is related to. Examples include
On Demand Instances,Standard Reserved Instances,Spot Instances, andSavings Plans. -
RESERVATION_ID - The unique identifier for an AWS Reservation Instance.
-
SAVINGS_PLAN_ARN - The unique identifier for your Savings Plans.
-
SAVINGS_PLANS_TYPE - Type of Savings Plans. Examples are
ComputeSavingsPlansandEC2InstanceSavingsPlans. -
SERVICE - The AWS service such as Amazon DynamoDB.
-
TENANCY - The tenancy of a resource. Examples are
Shared,Dedicated, andHost. -
USAGE_TYPE - The type of usage. An example is DataTransfer-In-Bytes. The response for the
GetDimensionValuesoperation includes a unit attribute. Examples include GB and Hrs. -
USAGE_TYPE_GROUP - The grouping of common usage types. An example is Amazon EC2: CloudWatch – Alarms. The response for this operation includes a unit attribute.
-
REGION - The AWS Region.
-
RECORD_TYPE - The different types of charges such as Reserved Instance (RI) fees, usage costs, tax refunds, and credits. Examples include
Usage,Credit,Tax,Recurring,Upfront, andSupport. -
RESOURCE_ID - The unique identifier of the resource. ResourceId is an opt-in feature that is available for the last 14 days, for the services that you opt in to in AWS Cost Management Console preferences.
Dimension values are case-sensitive and must match exactly when you use them in a filter. Use
GetDimensionValuesto list the values that are available for your account.If you set the context to
RESERVATIONS, you can use the following dimensions for searching:-
AZ - The Availability Zone. An example is
us-east-1a. -
INSTANCE_TYPE - The type of Amazon EC2 instance. An example is
m4.xlarge. -
INSTANCE_TYPE_FAMILY - The family of the instance type. An example is
m5. -
LINKED_ACCOUNT - The AWS ID of the member account. The
nameattribute contains the full name of the member account. -
PLATFORM - The platform of the reservation. For Amazon EC2, examples are
Linux/UNIX,Windows, andRed Hat Enterprise Linux. For Amazon Relational Database Service and Amazon ElastiCache, the value is the engine, such asMySQLorRedis. These values can differ from theCOST_AND_USAGEvalues, for exampleWindowsinstead ofWindows (Amazon VPC). -
REGION - The AWS Region.
-
SCOPE (Utilization only) - The scope of a Reserved Instance (RI). Values are
RegionandAvailability Zone. -
SERVICE - The AWS service of the reservation, such as Amazon Relational Database Service.
-
TENANCY - The tenancy of the reservation. Values are
SharedandDedicated.
If you set the context to
SAVINGS_PLANS, you can use the following dimensions for searching:-
SAVINGS_PLANS_TYPE - Type of Savings Plans. Examples are
ComputeSavingsPlans,EC2InstanceSavingsPlans,SageMakerSavingsPlans, andDatabaseSavingsPlans. -
PAYMENT_OPTION - The payment option for the given Savings Plans (for example, All Upfront)
-
REGION - The AWS Region.
-
INSTANCE_TYPE_FAMILY - The family of instances (For example,
m5) -
LINKED_ACCOUNT - The AWS ID of the member account. The
nameattribute contains the full name of the member account. -
SAVINGS_PLAN_ARN - The unique identifier for your Savings Plans.
Type: String
Valid Values:
COST_AND_USAGE | RESERVATIONS | SAVINGS_PLANSRequired: No
-
- Dimension
-
The name of the dimension. Each
Dimensionis available for a differentContext. For more information, seeContext.LINK_ACCOUNT_NAMEandSERVICE_CODEcan only be used in CostCategoryRule.PRODUCT_ATTRIBUTEreturns the product attribute keys that are available for your costs of supported services, or the values of the key that you specify inDimensionKey.PRODUCT_ATTRIBUTEis supported only in theCOST_AND_USAGEcontext.Type: String
Valid Values:
AZ | INSTANCE_TYPE | LINKED_ACCOUNT | PAYER_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 | ANOMALY_TOTAL_IMPACT_ABSOLUTE | ANOMALY_TOTAL_IMPACT_PERCENTAGE | PRODUCT_ATTRIBUTERequired: Yes
- DimensionKey
-
The product attribute key to return values for, such as
model. If you omitDimensionKeyor set it to an empty string, the response lists the product attribute keys that are available for your costs of supported services instead. For the supported services, see ProductAttributeValues.If you specify a key, the response lists the values of that key. If some of your costs have no value for the key, the response includes an empty-string value. Keys are case-sensitive, and a key that doesn't exist returns no values other than an empty string.
You can specify
DimensionKeyonly whenDimensionisPRODUCT_ATTRIBUTE. If you also specifySortBy,DimensionKeyis required. As a result, you can't list product attribute keys when you useSortBy.Type: String
Length Constraints: Minimum length of 0. Maximum length of 1024.
Pattern:
[\S\s]*Required: No
- Filter
-
To filter your results, use an Expression object.
The supported filter shapes depend on
Contextand on whether you specifySortBy:-
COST_AND_USAGEwithoutSortBy: a singleDimensions,Tags, orCostCategoriesexpression, or oneAndof such expressions.Or,Not, and anAndinside anotherAndaren't supported. -
COST_AND_USAGEwithSortBy:And,Or, andNotare supported, nested up to four levels. -
RESERVATIONSandSAVINGS_PLANS: a singleDimensionsexpression, aNotexpression that contains oneDimensionsexpression, or oneAndof such expressions. Each dimension can appear only once.Or,Tags,CostCategories, and anAndinside anotherAndaren't supported. ForRESERVATIONS, don't specifyMatchOptions. ForSAVINGS_PLANS,MatchOptionscan be onlyEQUALS, orEQUALSandCASE_SENSITIVE.SortByisn't supported in these contexts.
Type: Expression object
Required: No
-
- MaxResults
-
The maximum number of objects that are returned for this request. If MaxResults isn't specified with SortBy, the request returns 1000 results as the default value for this parameter. This field takes effect only when you specify SortBy in the request. If you don't specify SortBy, Cost Explorer ignores MaxResults.
For
GetDimensionValues, MaxResults has an upper limit of 1000.Type: Integer
Valid Range: Minimum value of 1.
Required: No
- NextPageToken
-
The token to retrieve the next set of results. AWS provides the token when the response from a previous call has more results than the maximum page size.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 8192.
Pattern:
[\S\s]*Required: No
- SearchString
-
The value that you want to search the filter values for.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 1024.
Pattern:
[\S\s]*Required: No
- SortBy
-
The value that you want to sort the data by.
The key represents cost and usage metrics. The following values are supported:
-
BlendedCost -
UnblendedCost -
AmortizedCost -
NetAmortizedCost -
NetUnblendedCost -
UsageQuantity -
NormalizedUsageAmount
The supported values for the
SortOrderkey areASCENDINGorDESCENDING.When you specify a
SortByparamater, the context must beCOST_AND_USAGE. Further, when usingSortBy,NextPageTokenandSearchStringaren't supported.Type: Array of SortDefinition objects
Required: No
-
- TimePeriod
-
The start date and end date for retrieving the dimension values. The start date is inclusive, but the end date is exclusive. For example, if
startis2017-01-01andendis2017-05-01, then the cost and usage data is retrieved from2017-01-01up to and including2017-04-30but not including2017-05-01.Type: DateInterval object
Required: Yes
Response Syntax
{
"DimensionValues": [
{
"Attributes": {
"string" : "string"
},
"Value": "string"
}
],
"NextPageToken": "string",
"ReturnSize": number,
"TotalSize": number
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- DimensionValues
-
The dimension values that match your request. Some dimensions are available only for a specific context.
If you set the context to
COST_AND_USAGE, you can use the following dimensions for searching:-
AZ - The Availability Zone. An example is
us-east-1a. -
DATABASE_ENGINE - The Amazon Relational Database Service database engine. Examples are
Aurora MySQL,Aurora PostgreSQL, andMySQL. -
INSTANCE_TYPE - The type of Amazon EC2 instance. An example is
m4.xlarge. -
LEGAL_ENTITY_NAME - The name of the organization that sells you AWS services, such as Amazon Web Services.
-
LINKED_ACCOUNT - The description in the attribute map that includes the full name of the member account. The value field contains the AWS ID of the member account.
-
OPERATING_SYSTEM - The operating system. Examples are
Linux/UNIX,Windows (Amazon VPC), andRed Hat Enterprise Linux. -
OPERATION - The action performed. Examples include
RunInstanceandCreateBucket. -
PLATFORM - The operating system or platform of the usage. Examples are
Linux/UNIX,Windows (Amazon VPC), andRed Hat Enterprise Linux. -
PURCHASE_TYPE - The reservation type of the purchase to which this usage is related. Examples include
On Demand Instances,Standard Reserved Instances,Spot Instances, andSavings Plans. -
SERVICE - The AWS service such as Amazon DynamoDB.
-
USAGE_TYPE - The type of usage. An example is DataTransfer-In-Bytes. The response for the
GetDimensionValuesoperation includes a unit attribute. Examples include GB and Hrs. -
USAGE_TYPE_GROUP - The grouping of common usage types. An example is Amazon EC2: CloudWatch – Alarms. The response for this operation includes a unit attribute.
-
RECORD_TYPE - The different types of charges such as RI fees, usage costs, tax refunds, and credits. Examples include
Usage,Credit,Tax,Recurring,Upfront, andSupport. -
RESOURCE_ID - The unique identifier of the resource. ResourceId is an opt-in feature that is available for the last 14 days. You can opt in by enabling resource-level data for the services that you want in AWS Cost Management Console preferences.
If you set the context to
RESERVATIONS, you can use the following dimensions for searching:-
AZ - The Availability Zone. An example is
us-east-1a. -
INSTANCE_TYPE - The type of Amazon EC2 instance. An example is
m4.xlarge. -
INSTANCE_TYPE_FAMILY - The family of the instance type. An example is
m5. -
LINKED_ACCOUNT - The AWS ID of the member account. The
nameattribute contains the full name of the member account. -
PLATFORM - The platform of the reservation. For Amazon EC2, examples are
Linux/UNIX,Windows, andRed Hat Enterprise Linux. For Amazon Relational Database Service and Amazon ElastiCache, the value is the engine, such asMySQLorRedis. These values can differ from theCOST_AND_USAGEvalues, for exampleWindowsinstead ofWindows (Amazon VPC). -
REGION - The AWS Region.
-
SCOPE (Utilization only) - The scope of a Reserved Instance (RI). Values are
RegionandAvailability Zone. -
SERVICE - The AWS service of the reservation, such as Amazon Relational Database Service.
-
TENANCY - The tenancy of the reservation. Values are
SharedandDedicated.
If you set the context to
SAVINGS_PLANS, you can use the following dimensions for searching:-
SAVINGS_PLANS_TYPE - Type of Savings Plans. Examples are
ComputeSavingsPlans,EC2InstanceSavingsPlans,SageMakerSavingsPlans, andDatabaseSavingsPlans. -
PAYMENT_OPTION - Payment option for the given Savings Plans (for example, All Upfront)
-
REGION - The AWS Region.
-
INSTANCE_TYPE_FAMILY - The family of instances (For example,
m5) -
LINKED_ACCOUNT - The AWS ID of the member account. The
nameattribute contains the full name of the member account. -
SAVINGS_PLAN_ARN - The unique identifier for your Savings Plan
Type: Array of DimensionValuesWithAttributes objects
-
- NextPageToken
-
The token for the next set of retrievable results. AWS provides the token when the response from a previous call has more results than the maximum page size.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 8192.
Pattern:
[\S\s]* - ReturnSize
-
The number of results that AWS returned at one time.
Type: Integer
- TotalSize
-
The total number of search results. When you specify
SortBy,TotalSizeequalsReturnSize: the number of values that Cost Explorer returns after it applies theMaxResultslimit, not the number of values that match the request. In theCOST_AND_USAGEcontext withoutSortBy,TotalSizecan be greater thanReturnSize.Type: Integer
Errors
For information about the errors that are common to all actions, see Common Error Types.
- BillExpirationException
-
The requested report expired. Update the date interval and try again.
HTTP Status Code: 400
- BillingViewHealthStatusException
-
The billing view status must be
HEALTHYto perform this action. Try again when the status isHEALTHY.HTTP Status Code: 400
- DataUnavailableException
-
The requested data is unavailable.
HTTP Status Code: 400
- InvalidNextTokenException
-
The pagination token is invalid. Try again without a pagination token.
HTTP Status Code: 400
- LimitExceededException
-
You made too many calls in a short period of time. Try again later.
HTTP Status Code: 400
- RequestChangedException
-
Your request parameters changed between pages. Try again with the old parameters or without a pagination token.
HTTP Status Code: 400
- ResourceNotFoundException
-
The specified ARN in the request doesn't exist.
HTTP Status Code: 400
Examples
Example
The following is a sample request and response of the
GetDimensionValues operation that enables you to search for all the member
accounts in an organization in AWS Organizations that have "Elastic" in their
name.
Sample Request
POST / HTTP/1.1
Host: ce.us-east-1.amazonaws.com
x-amz-Date: <Date>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=contenttype;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid,Signature=<Signature>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Connection: Keep-Alive
X-Amz-Target: AWSInsightsIndexService.GetDimensionValues
{
"TimePeriod": {
"Start": "2017-01-01",
"End": "2017-05-18"
},
"SearchString": "Elastic",
"Dimension": "Service"
}
Sample Response
HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
//Attributes are optional metadata that are returned depending on the dimension that you select.
{
"DimensionValues": [
{
"Attributes": {},
"Value": "Amazon ElastiCache"
},
{
"Attributes": {},
"Value": "EC2 - Other"
},
{
"Attributes": {},
"Value": "Amazon Elastic Compute Cloud - Compute"
},
{
"Attributes": {},
"Value": "Amazon Elasticsearch Service"
}
],
"ReturnSize": 4,
"TotalSize": 4
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: