AWS Cost Explorer Service

Cost Management APIs

AWS Cost Explorer Service: Cost Management APIs

Copyright © 2018 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
 AWS Cost Explorer Service Cost Management APIs

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
 AWS Cost Explorer Service Cost Management APIs

Table of Contents
Welcome ........................................................................................................................................... 1
AWS Cost Explorer Service .......................................................................................................... 1
AWS Price List Service ................................................................................................................ 1
Actions ............................................................................................................................................. 2
AWS Cost Explorer Service .......................................................................................................... 2
GetCostAndUsage ............................................................................................................... 3
GetDimensionValues ........................................................................................................... 9
GetReservationUtilization .................................................................................................. 14
GetTags ........................................................................................................................... 20
AWS Price List Service ............................................................................................................... 22
DescribeServices ............................................................................................................... 24
GetAttributeValues ........................................................................................................... 28
GetProducts ..................................................................................................................... 32
Data Types ...................................................................................................................................... 36
AWS Cost Explorer Service ......................................................................................................... 36
DateInterval ..................................................................................................................... 37
DimensionValues .............................................................................................................. 38
DimensionValuesWithAttributes .......................................................................................... 39
Expression ....................................................................................................................... 40
Group ............................................................................................................................. 42
GroupDefinition ................................................................................................................ 43
MetricValue ..................................................................................................................... 44
ReservationAggregates ...................................................................................................... 45
ReservationUtilizationGroup ............................................................................................... 46
ResultByTime ................................................................................................................... 47
TagValues ........................................................................................................................ 48
UtilizationByTime ............................................................................................................. 49
AWS Price List Service ............................................................................................................... 49
AttributeValue .................................................................................................................. 50
Filter ............................................................................................................................... 51
Service ............................................................................................................................ 52
Common Parameters ........................................................................................................................ 53
Common Errors ................................................................................................................................ 55

iii
 AWS Cost Explorer Service Cost Management APIs
AWS Cost Explorer Service

Welcome
AWS Cost Explorer Service
The Cost Explorer API allows you to programmatically query your cost and usage data. You can query
for aggregated data such as total monthly costs or total daily usage. You can also query for granular
data, such as the number of daily write operations for DynamoDB database tables in your production
environment.

Service Endpoint

The Cost Explorer API provides the following endpoint:

• https://ce.us-east-1.amazonaws.com

AWS Price List Service

AWS Price List Service API is a centralized and convenient way to programmatically query Amazon Web
Services for services, products, and pricing information. The AWS Price List Service uses standardized
product attributes such as Location, Storage Class, and Operating System, and provides prices
at the SKU level. You can use the AWS Price List Service to build cost control and scenario planning tools,
reconcile billing data, forecast future spend for budgeting purposes, and provide cost benefit analysis
that compare your internal workloads with AWS.

Use GetServices without a service code to retrieve the service codes for all AWS services, then
GetServices with a service code to retreive the attribute names for that service. After you have the
service code and attribute names, you can use GetAttributeValues to see what values are available
for an attribute. With the service code and an attribute name and value, you can use GetProducts to
find specific products that you're interested in, such as an AmazonEC2 instance, with a Provisioned
IOPS volumeType.

Service Endpoint

AWS Price List Service API provides the following two endpoints:

• https://api.pricing.us-east-1.amazonaws.com
• https://api.pricing.ap-south-1.amazonaws.com

1
 AWS Cost Explorer Service Cost Management APIs
AWS Cost Explorer Service

Actions
The following actions are supported by AWS Cost Explorer Service:

• GetCostAndUsage (p. 3)
• GetDimensionValues (p. 9)
• GetReservationUtilization (p. 14)
• GetTags (p. 20)

The following actions are supported by AWS Price List Service:

• DescribeServices (p. 24)

• GetAttributeValues (p. 28)
• GetProducts (p. 32)

AWS Cost Explorer Service

The following actions are supported by AWS Cost Explorer Service:

• GetCostAndUsage (p. 3)
• GetDimensionValues (p. 9)
• GetReservationUtilization (p. 14)
• GetTags (p. 20)

2
 AWS Cost Explorer Service Cost Management APIs
GetCostAndUsage

GetCostAndUsage
Service: AWS Cost Explorer Service

Retrieve cost and usage metrics for your account. You can specify which cost and usage-related metric,
such as BlendedCosts or UsageQuantity, that you want the request to return. You can also filter
and group your data by various dimensions, such as SERVICE or AZ, in a specific time range. See
the GetDimensionValues action for a complete list of the valid dimensions. Master accounts in an
organization have access to all member accounts.

Request Syntax
{
"Filter": {
"And": [
"Expression"
],
"Dimensions": {
"Key": "string",
"Values": [ "string" ]
},
"Not": "Expression",
"Or": [
"Expression"
],
"Tags": {
"Key": "string",
"Values": [ "string" ]
}
},
"Granularity": "string",
"GroupBy": [
{
"Key": "string",
"Type": "string"
}
],
"Metrics": [ "string" ],
"NextPageToken": "string",
"TimePeriod": {
"End": "string",
"Start": "string"
}
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 53).

The request accepts the following data in JSON format.

Filter (p. 3)

Filters AWS costs by different dimensions. For example, you can specify SERVICE and
LINKED_ACCOUNT and get the costs associated with that account's usage of that service. You can
nest Expression objects to define any combination of dimension filters. For more information, see
the Expression object or More Examples.

Type: Expression (p. 40) object

3
 AWS Cost Explorer Service Cost Management APIs
GetCostAndUsage

Required: No
Granularity (p. 3)

Sets the AWS cost granularity to MONTHLY or DAILY.

Type: String

Valid Values: DAILY | MONTHLY

Required: No
GroupBy (p. 3)

You can group AWS costs using up to two different groups, either dimensions, tag keys, or both.

When you group by tag key, you get all tag values, including empty strings.

Valid values are: AZ, INSTANCE_TYPE, LINKED_ACCOUNT, OPERATION, PURCHASE_TYPE, SERVICE,

USAGE_TYPE, TAGS, and PLATFORM.

Type: Array of GroupDefinition (p. 43) objects

Required: No
Metrics (p. 3)

Which metrics are returned in the query. For more information about blended and unblended rates,
see https://aws.amazon.com/premiumsupport/knowledge-center/blended-rates-intro/.

Valid values are BlendedCost, UnblendedCost, and UsageQuantity.

Note
If you return the UsageQuantity metric, the service aggregates all usage numbers
without taking into account the units. For example, if you aggregate usageQuantity
across all of EC2, the results aren't meaningful because EC2 compute hours and data
transfer are measured in different units (for example, hours vs. GB). To get more meaningful
UsageQuantity metrics, filter by UsageType or UsageTypeGroups.

Type: Array of strings

Required: No
NextPageToken (p. 3)

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

Required: No
TimePeriod (p. 3)

Sets the start and end dates for retrieving AWS costs. The start date is inclusive, but the end date
is exclusive. For example, if start is 2017-01-01 and end is 2017-05-01, then the cost and
usage data is retrieved from 2017-01-01 up to and including 2017-04-30 but not including
2017-05-01.

Type: DateInterval (p. 37) object

Required: No

4
 AWS Cost Explorer Service Cost Management APIs
GetCostAndUsage

Response Syntax
{
"GroupDefinitions": [
{
"Key": "string",
"Type": "string"
}
],
"NextPageToken": "string",
"ResultsByTime": [
{
"Estimated": boolean,
"Groups": [
{
"Keys": [ "string" ],
"Metrics": {
"string" : {
"Amount": "string",
"Unit": "string"
}
}
}
],
"TimePeriod": {
"End": "string",
"Start": "string"
},
"Total": {
"string" : {
"Amount": "string",
"Unit": "string"
}
}
}
]
}

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.

GroupDefinitions (p. 5)

The groups specified by the the Filter or GroupBy parameters in the request.

Type: Array of GroupDefinition (p. 43) objects

NextPageToken (p. 5)

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
ResultsByTime (p. 5)

The time period covered by the results in the response.

Type: Array of ResultByTime (p. 47) objects

5
 AWS Cost Explorer Service Cost Management APIs
GetCostAndUsage

Errors
For information about the errors that are common to all actions, see Common Errors (p. 55).

LimitExceededException

You made too many calls in a short period of time. Try again later.

HTTP Status Code: 400

Example

The following is a sample request and response of the GetCostAndUsage operation that allows you
to retrieve your Amazon S3 costs. For more complex examples, such as multi-level groupings, see More
Examples.

Sample Request

POST / HTTP/1.1
Host: api.ce.<region>.<domain>
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.GetCostAndUsage
{
"TimePeriod": {
"Start":"2017-09-01",
"End": "2017-10-01"
},
"Granularity": "MONTHLY",
"Filter": {
"Dimensions": {
"Key": "SERVICE",
"Values": [
"Amazon Simple Storage Service"
]
}
},
"GroupBy":[
{
"Type":"DIMENSION",
"Key":"SERVICE"
},
{
"Type":"TAG",
"Key":"Environment"
}
],
"Metrics":["BlendedCost", "UnblendedCost", "UsageQuantity"]
}

Sample Response

HTTP/1.1 200 OK

6
 AWS Cost Explorer Service Cost Management APIs
GetCostAndUsage

x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
"GroupDefinitions": [
{
"Key": "SERVICE",
"Type": "DIMENSION"
},
{
"Key": "Environment",
"Type": "TAG"
}
],
"ResultsByTime": [
{
"Estimated": false,
"Groups": [
{
"Keys": [
"Amazon Simple Storage Service",
"Environment$Prod"
],
"Metrics": {
"BlendedCost": {
"Amount": "39.1603300457",
"Unit": "USD"
},
"UnblendedCost": {
"Amount": "39.1603300457",
"Unit": "USD"
},
"UsageQuantity": {
"Amount": "173842.5440074444",
"Unit": "N/A"
}
}
},
{
"Keys": [
"Amazon Simple Storage Service",
"Environment$Test"
],
"Metrics": {
"BlendedCost": {
"Amount": "0.1337464807",
"Unit": "USD"
},
"UnblendedCost": {
"Amount": "0.1337464807",
"Unit": "USD"
},
"UsageQuantity": {
"Amount": "15992.0786663399",
"Unit": "N/A"
}
}
}
],
"TimePeriod": {
"End": "2017-10-01",
"Start": "2017-09-01"
},
"Total": {}
}

7
 AWS Cost Explorer Service Cost Management APIs
GetCostAndUsage

]
}

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

8
 AWS Cost Explorer Service Cost Management APIs
GetDimensionValues

GetDimensionValues
Service: AWS Cost Explorer Service

You can use GetDimensionValues to retrieve all available filter values for a specific filter over a period
of time. You can search the dimension values for an arbitrary string.

Request Syntax
{
"Context": "string",
"Dimension": "string",
"NextPageToken": "string",
"SearchString": "string",
"TimePeriod": {
"End": "string",
"Start": "string"
}
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 53).

The request accepts the following data in JSON format.

Context (p. 9)

The context for the call to GetDimensionValues. This can be RESERVATIONS or

COST_AND_USAGE. The default value is COST_AND_USAGE. If the context is set to RESERVATIONS,
the resulting dimension values can be used in the GetReservationUtilization action. If
the context is set to COST_AND_USAGE, , the resulting dimension values can be used in the
GetCostAndUsage operation.

If you set the context to CostAndUsage, you can use the following dimensions for searching:
• AZ - The Availability Zone. An example is us-east-1a.
• INSTANCE_TYPE - The type of EC2 instance. An example is m4.xlarge.
• 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
• OPERATION - The action performed. Examples include RunInstance and CreateBucket.
• PURCHASE_TYPE - The reservation type of the purchase to which this usage is related. Examples
include: On Demand Instances and Standard Reserved Instances
• SERVICE - The AWS service such as DynamoDB.
• USAGE_TYPE - The type of usage. An example is DataTransfer-In-Bytes. The response for the
GetDimensionValues action includes a unit attribute, examples of which include GB and Hrs.
• USAGE_TYPE_GROUP - The grouping of common usage types. An example is EC2: CloudWatch –
Alarms. The response for this action includes a unit attribute.
• RECORD_TYPE - The different types of charges such as RI fees, usage costs, tax refunds, and
credits

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 EC2 instance. An example is m4.xlarge.

9
 AWS Cost Explorer Service Cost Management APIs
GetDimensionValues

• 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
• PLATFORM - The operating system. Examples are Windows or Linux.
• REGION - The AWS region.
• SCOPE - The scope of a reserved instance (RI). Values are regional or a single availability zone.
• TENANCY - The tenancy of a resource. Examples are shared or dedicated.

Type: String

Valid Values: COST_AND_USAGE | RESERVATIONS

Required: No
Dimension (p. 9)

The name of the dimension. Different Dimensionsare available for different Contexts. For more
information, see Context.

Type: String

Valid Values: AZ | INSTANCE_TYPE | LINKED_ACCOUNT | OPERATION | PURCHASE_TYPE

| REGION | SERVICE | USAGE_TYPE | USAGE_TYPE_GROUP | RECORD_TYPE |
OPERATING_SYSTEM | TENANCY | SCOPE | PLATFORM | SUBSCRIPTION_ID

Required: Yes
NextPageToken (p. 9)

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

Required: No
SearchString (p. 9)

The value that you want to search the filter values for.

Type: String

Required: No
TimePeriod (p. 9)

The start and end dates for retrieving the dimension values. The start date is inclusive, but the end
date is exclusive. For example, if start is 2017-01-01 and end is 2017-05-01, then the cost
and usage data is retrieved from 2017-01-01 up to and including 2017-04-30 but not including
2017-05-01.

Type: DateInterval (p. 37) object

Required: Yes

Response Syntax
{
"DimensionValues": [
{
"Attributes": {

10
 AWS Cost Explorer Service Cost Management APIs
GetDimensionValues

"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 (p. 10)

The filters that you used to filter your request. Some dimensions are available only for a specific
context:

If you set the context to CostAndUsage, you can use the following dimensions for searching:
• AZ - The Availability Zone. An example is us-east-1a.
• INSTANCE_TYPE - The type of EC2 instance. An example is m4.xlarge.
• 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
• OPERATION - The action performed. Examples include RunInstance and CreateBucket.
• PURCHASE_TYPE - The reservation type of the purchase to which this usage is related. Examples
include: On Demand Instances and Standard Reserved Instances
• SERVICE - The AWS service such as DynamoDB.
• USAGE_TYPE - The type of usage. An example is DataTransfer-In-Bytes. The response for the
GetDimensionValues action includes a unit attribute, examples of which include GB and Hrs.
• USAGE_TYPE_GROUP - The grouping of common usage types. An example is EC2: CloudWatch –
Alarms. The response for this action includes a unit attribute.
• RECORD_TYPE - The different types of charges such as RI fees, usage costs, tax refunds, and
credits

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 EC2 instance. An example is m4.xlarge.
• 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
• PLATFORM - The operating system. Examples are Windows or Linux.
• REGION - The AWS region.
• SCOPE - The scope of a reserved instance (RI). Values are regional or a single availability zone.
• TENANCY - The tenancy of a resource. Examples are shared or dedicated.

Type: Array of DimensionValuesWithAttributes (p. 39) objects

NextPageToken (p. 10)

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

11
 AWS Cost Explorer Service Cost Management APIs
GetDimensionValues

ReturnSize (p. 10)

The number of results that AWS returned at one time.

Type: Integer
TotalSize (p. 10)

The total number of search results.

Type: Integer

Errors
For information about the errors that are common to all actions, see Common Errors (p. 55).

LimitExceededException

You made too many calls in a short period of time. Try again later.

HTTP Status Code: 400

Example

The following is a sample request and response of the GetDimensionValues operation that allows you
to search for all the member accounts in an organization that have "Elastic" in their name:

Sample Request

POST / HTTP/1.1
Host: api.ce.<region>.<domain>
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: AWSCostExplorerService.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.
{

12
 AWS Cost Explorer Service Cost Management APIs
GetDimensionValues

"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:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

13
 AWS Cost Explorer Service Cost Management APIs
GetReservationUtilization

GetReservationUtilization
Service: AWS Cost Explorer Service

You can retrieve the Reservation utilization for your account. Master accounts in an organization have
access to their associated member accounts. You can filter data by dimensions in a time period. You can
use GetDimensionValues to determine the possible dimension values. Currently, you can group only
by SUBSCRIPTION_ID.

Request Syntax
{
"Filter": {
"And": [
"Expression"
],
"Dimensions": {
"Key": "string",
"Values": [ "string" ]
},
"Not": "Expression",
"Or": [
"Expression"
],
"Tags": {
"Key": "string",
"Values": [ "string" ]
}
},
"Granularity": "string",
"GroupBy": [
{
"Key": "string",
"Type": "string"
}
],
"NextPageToken": "string",
"TimePeriod": {
"End": "string",
"Start": "string"
}
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 53).

The request accepts the following data in JSON format.

Filter (p. 14)

Filters utilization data by using different dimensions. GetReservationUtilization uses

the same Expression object as the other operations, but only AND is supported among each
dimension, and nesting is supported up to only one level deep. If there are multiple values for a
dimension, they are OR'd together.

Type: Expression (p. 40) object

Required: No

14
 AWS Cost Explorer Service Cost Management APIs
GetReservationUtilization

Granularity (p. 14)

Sets the AWS cost granularity to MONTHLY or DAILY. If both GroupBy and granularity are not
set, GetReservationUtilization defaults to DAILY. If GroupBy is set, Granularity can't be
set, and the response object doesn't include MONTHLY or DAILY granularity.

Type: String

Valid Values: DAILY | MONTHLY

Required: No
GroupBy (p. 14)

Groups only by SUBSCRIPTION_ID. Metadata is included.

Type: Array of GroupDefinition (p. 43) objects

Required: No
NextPageToken (p. 14)

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

Required: No
TimePeriod (p. 14)

Sets the start and end dates for retrieving reserve instance (RI) utilization. The start date is inclusive,
but the end date is exclusive. For example, if start is 2017-01-01 and end is 2017-05-01, then
the cost and usage data is retrieved from 2017-01-01 up to and including 2017-04-30 but not
including 2017-05-01.

Type: DateInterval (p. 37) object

Required: Yes

Response Syntax
{
"NextPageToken": "string",
"Total": {
"PurchasedHours": "string",
"TotalActualHours": "string",
"UnusedHours": "string",
"UtilizationPercentage": "string"
},
"UtilizationsByTime": [
{
"Groups": [
{
"Attributes": {
"string" : "string"
},
"Key": "string",
"Utilization": {
"PurchasedHours": "string",
"TotalActualHours": "string",
"UnusedHours": "string",

15
 AWS Cost Explorer Service Cost Management APIs
GetReservationUtilization

"UtilizationPercentage": "string"
},
"Value": "string"
}
],
"TimePeriod": {
"End": "string",
"Start": "string"
},
"Total": {
"PurchasedHours": "string",
"TotalActualHours": "string",
"UnusedHours": "string",
"UtilizationPercentage": "string"
}
}
]
}

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.

NextPageToken (p. 15)

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
Total (p. 15)

The total amount of time that you utilized your RIs.

Type: ReservationAggregates (p. 45) object

UtilizationsByTime (p. 15)

The amount of time that you utilized your RIs.

Type: Array of UtilizationByTime (p. 49) objects

Errors
For information about the errors that are common to all actions, see Common Errors (p. 55).

LimitExceededException

You made too many calls in a short period of time. Try again later.

HTTP Status Code: 400

Example

The following is a sample request and response of the GetReservationUtilization operation that
allows you to retrieve your RI utilization for all t2.nano instance types from 2017-01-01 to 2017-05-01:

16
 AWS Cost Explorer Service Cost Management APIs
GetReservationUtilization

Sample Request

POST / HTTP/1.1
Host: api.ce.<region>.<domain>
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: AWSCostExplorerService.GetReservationUtilization
{
"TimePeriod": {
"Start":"2017-07-01",
"End": "2017-10-01"
},
"Filter": {
"Dimensions": {
"Key": "INSTANCE_TYPE",
"Values": [
"t2.nano"
]
}
},
"GroupBy":[
{
"Type":"Dimension",
"Key":"SUBSCRIPTION_ID"
}
]
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
"UtilizationsByTime": [
{
"Groups": [
{
"Attributes": {
"AccountId": "0123456789",
"AccountName": null,
"AvailabilityZone": "",
"CancellationDateTime": "2019-09-28T15:22:31.000Z",
"EndDateTime": "2019-09-28T15:22:31.000Z",
"InstanceType": "t2.nano",
"LeaseId": null,
"NumberOfInstances": "1",
"OfferingType": "convertible",
"Platform": "Linux/UNIX",
"Region": "us-east-1",
"Scope": "Region",
"StartDateTime": "2016-09-28T15:22:32.000Z",
"SubscriptionId": "359809062",
"SubscriptionStatus": "Active",
"SubscriptionType": "All Upfront",
"Tenancy": "Shared"

17
 AWS Cost Explorer Service Cost Management APIs
GetReservationUtilization

},
"Key": "SUBSCRIPTION_ID",
"Utilization": {
"PurchasedHours": 2208,
"TotalActualHours": 2208,
"UnusedHours": 0,
"UtilizationPercentage": 100
},
"Value": "359809062"
},
{
"Attributes": {
"AccountId": "0123456789",
"AccountName": null,
"AvailabilityZone": "us-east-1d",
"CancellationDateTime": "2017-09-28T15:22:31.000Z",
"EndDateTime": "2017-09-28T15:22:31.000Z",
"InstanceType": "t2.nano",
"LeaseId": null,
"NumberOfInstances": "1",
"OfferingType": "Standard",
"Platform": "Linux/UNIX",
"Region": "us-east-1",
"Scope": "Availability Zone",
"StartDateTime": "2016-09-28T15:22:32.000Z",
"SubscriptionId": "359809070",
"SubscriptionStatus": "Active",
"SubscriptionType": "All Upfront",
"Tenancy": "Shared"
},
"Key": "SUBSCRIPTION_ID",
"Utilization": {
"PurchasedHours": 2151,
"TotalActualHours": 2151,
"UnusedHours": 0,
"UtilizationPercentage": 100
},
"Value": "359809070"
},
{
"Attributes": {
"AccountId": "0123456789",
"AccountName": null,
"AvailabilityZone": "us-west-2a",
"CancellationDateTime": "2017-09-20T04:06:02.000Z",
"EndDateTime": "2017-09-20T04:06:02.000Z",
"InstanceType": "t2.nano",
"LeaseId": null,
"NumberOfInstances": "1",
"OfferingType": "Standard",
"Platform": "Linux/UNIX",
"Region": "us-west-2",
"Scope": "Availability Zone",
"StartDateTime": "2016-09-20T04:06:03.000Z",
"SubscriptionId": "353571154",
"SubscriptionStatus": "Active",
"SubscriptionType": "Partial Upfront",
"Tenancy": "Shared"
},
"Key": "SUBSCRIPTION_ID",
"Utilization": {
"PurchasedHours": 1948,
"TotalActualHours": 0,
"UnusedHours": 1948,
"UtilizationPercentage": 0
},

18
 AWS Cost Explorer Service Cost Management APIs
GetReservationUtilization

"Value": "353571154"
}
],
"TimePeriod": {
"End": "2017-10-01",
"Start": "2017-07-01"
},
"Total": {
"PurchasedHours": 6307,
"TotalActualHours": 4359,
"UnusedHours": 1948,
"UtilizationPercentage": 69.11368320913270968764864436340574
}
}
]
}

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

19
 AWS Cost Explorer Service Cost Management APIs
GetTags

GetTags
Service: AWS Cost Explorer Service

You can query for available tag keys and tag values for a specified period. You can search the tag values
for an arbitrary string.

Request Syntax
{
"NextPageToken": "string",
"SearchString": "string",
"TagKey": "string",
"TimePeriod": {
"End": "string",
"Start": "string"
}
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 53).

The request accepts the following data in JSON format.

NextPageToken (p. 20)

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

Required: No
SearchString (p. 20)

The value that you want to search for.

Type: String

Required: No
TagKey (p. 20)

The key of the tag that you want to return values for.

Type: String

Required: No
TimePeriod (p. 20)

The start and end dates for retrieving the dimension values. The start date is inclusive, but the end
date is exclusive. For example, if start is 2017-01-01 and end is 2017-05-01, then the cost
and usage data is retrieved from 2017-01-01 up to and including 2017-04-30 but not including
2017-05-01.

Type: DateInterval (p. 37) object

Required: Yes

20
 AWS Cost Explorer Service Cost Management APIs
GetTags

Response Syntax
{
"NextPageToken": "string",
"ReturnSize": number,
"Tags": [ "string" ],
"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.

NextPageToken (p. 21)

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
ReturnSize (p. 21)

The number of query results that AWS returns at a time.

Type: Integer
Tags (p. 21)

The tags that match your request.

Type: Array of strings

TotalSize (p. 21)

The total number of query results.

Type: Integer

Errors
For information about the errors that are common to all actions, see Common Errors (p. 55).

LimitExceededException

You made too many calls in a short period of time. Try again later.

HTTP Status Code: 400

Example

The following example shows how to retrieve the list of tag keys using the GetTags operation:

Sample Request

POST / HTTP/1.1

21
 AWS Cost Explorer Service Cost Management APIs
AWS Price List Service

Host: api.ce.<region>.<domain>
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: CostExplorer.GetTags
{
“TimePeriod": {
“Start": "2017-01-01",
“End": "2017-05-18"
},
“TagKey”: "Project”,
“SearchString”: “secretProject”
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
“ReturnSize": 2,
“Tags": [
“secretProject1”,
“secretProject2”
],
“TotalSize": 2

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

AWS Price List Service

The following actions are supported by AWS Price List Service:

• DescribeServices (p. 24)

• GetAttributeValues (p. 28)
• GetProducts (p. 32)

22
AWS Cost Explorer Service Cost Management APIs
AWS Price List Service

23
 AWS Cost Explorer Service Cost Management APIs
DescribeServices

DescribeServices
Service: AWS Price List Service

Returns the metadata for one service or a list of the metadata for all services. Use this without a
service code to get the service codes for all services. Use it with a service code, such as AmazonEC2,
to get information specific to that service, such as the attribute names available for that service. For
example, some of the attribute names available for EC2 are volumeType, maxIopsVolume, operation,
locationType, and instanceCapacity10xlarge.

Request Syntax
{
"FormatVersion": "string",
"MaxResults": number,
"NextToken": "string",
"ServiceCode": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 53).

The request accepts the following data in JSON format.

FormatVersion (p. 24)

The format version that you want the response to be in.

Valid values are: aws_v1

Type: String

Required: No
MaxResults (p. 24)

The maximum number of results that you want returned in the response.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No
NextToken (p. 24)

The pagination token that indicates the next set of results that you want to retrieve.

Type: String

Required: No
ServiceCode (p. 24)

The code for the service whose information you want to retrieve, such as AmazonEC2. You can use
the ServiceCode to filter the results in a GetProducts call. To retrieve a list of all services, leave
this blank.

Type: String

Required: No

24
 AWS Cost Explorer Service Cost Management APIs
DescribeServices

Response Syntax
{
"FormatVersion": "string",
"NextToken": "string",
"Services": [
{
"AttributeNames": [ "string" ],
"ServiceCode": "string"
}
]
}

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.

FormatVersion (p. 25)

The format version of the response. For example, aws_v1.

Type: String
NextToken (p. 25)

The pagination token for the next set of retreivable results.

Type: String
Services (p. 25)

The service metadata for the service or services in the response.

Type: Array of Service (p. 52) objects

Errors
For information about the errors that are common to all actions, see Common Errors (p. 55).

ExpiredNextTokenException

The pagination token expired. Try again without a pagination token.

HTTP Status Code: 400

InternalErrorException

An error on the server occurred during the processing of your request. Try again later.

HTTP Status Code: 400

InvalidNextTokenException

The pagination token is invalid. Try again without a pagination token.

HTTP Status Code: 400

InvalidParameterException

One or more parameters had an invalid value.

25
 AWS Cost Explorer Service Cost Management APIs
DescribeServices

HTTP Status Code: 400

NotFoundException

The requested resource can't be found.

HTTP Status Code: 400

Example
The following is a sample request and response of the GetService operation.
Sample Request

POST / HTTP/1.1
Host: api.pricing.<region>.<domain>
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: AWSPriceListService.DescribeServices
{
"ServiceCode": "AmazonEC2",
"FormatVersion": "aws_v1",
"NextToken": null,
"MaxResults": 1
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
"FormatVersion": "aws_v1",
"NextToken": "abcdefg123",
"Services": [
{
"AttributeNames": [
"volumeType",
"maxIopsvolume",
"instanceCapacity10xlarge",
"locationType",
"operation"
],
"ServiceCode": "AmazonEC2"
}
]
}

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

26
 AWS Cost Explorer Service Cost Management APIs
DescribeServices

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

27
 AWS Cost Explorer Service Cost Management APIs
GetAttributeValues

GetAttributeValues
Service: AWS Price List Service

Returns a list of attribute values. Attibutes are similar to the details in a Price List API offer file. For a list
of available attributes, see Offer File Definitions in the AWS Billing and Cost Management User Guide.

Request Syntax
{
"AttributeName": "string",
"MaxResults": number,
"NextToken": "string",
"ServiceCode": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 53).

The request accepts the following data in JSON format.

AttributeName (p. 28)

The name of the attribute that you want to retrieve the values for, such as volumeType.

Type: String

Required: Yes
MaxResults (p. 28)

The maximum number of results to return in response.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No
NextToken (p. 28)

The pagination token that indicates the next set of results that you want to retrieve.

Type: String

Required: No
ServiceCode (p. 28)

The service code for the service whose attributes you want to retrieve. For example, if you want the
retrieve an EC2 attribute, use AmazonEC2.

Type: String

Required: Yes

Response Syntax
{

28
 AWS Cost Explorer Service Cost Management APIs
GetAttributeValues

"AttributeValues": [
{
"Value": "string"
}
],
"NextToken": "string"
}

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.

AttributeValues (p. 28)

The list of values for an attribute. For example, Throughput Optimized HDD and Provisioned
IOPS are two available values for the AmazonEC2 volumeType.

Type: Array of AttributeValue (p. 50) objects

NextToken (p. 28)

The pagination token that indicates the next set of results to retrieve.

Type: String

Errors
For information about the errors that are common to all actions, see Common Errors (p. 55).

ExpiredNextTokenException

The pagination token expired. Try again without a pagination token.

HTTP Status Code: 400

InternalErrorException

An error on the server occurred during the processing of your request. Try again later.

HTTP Status Code: 400

InvalidNextTokenException

The pagination token is invalid. Try again without a pagination token.

HTTP Status Code: 400

InvalidParameterException

One or more parameters had an invalid value.

HTTP Status Code: 400

NotFoundException

The requested resource can't be found.

HTTP Status Code: 400

29
 AWS Cost Explorer Service Cost Management APIs
GetAttributeValues

Example
The following is a sample request and response of the GetAttributeValues
operation.
Sample Request

POST / HTTP/1.1
Host: api.pricing.<region>.<domain>
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: AWSPriceListService.GetAttributeValues
{
"ServiceCode": "AmazonEC2",
"AttributeName": "volumeType",
"NextToken": null,
"MaxResults": 2
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
"AttributeValues": [
{
"Value": "Throughput Optimized HDD"
},
{
"Value": "Provisioned IOPS"
}
],
"NextToken":
"GpgauTGIY7LGezucl5LV0w==:7GzYJ0nw0DBTJ2J66EoTIIynE6O1uXwQtTRqioJzQadBnDVgHPzI1en4BUQnPCLpzeBk9RQQAWaF
+Z/9/cTw9GldnPOHN98+FdmJP7wKU3QQpQ8MQr5KOeBkIsAqvAQYdL0DkL7tHwPtE5iCEByAmg9gcC/
yBU1vAOsf7R3VaNN4M5jMDv3woSWqASSIlBVB6tgW78YL22KhssoItM/jWW+aP6Jqtq4mldxp/ct6DWAl+xLFwHU/
CbketimPPXyqHF3/UXDw=="
}

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java

30
 AWS Cost Explorer Service Cost Management APIs
GetAttributeValues

• AWS SDK for JavaScript

• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

31
 AWS Cost Explorer Service Cost Management APIs
GetProducts

GetProducts
Service: AWS Price List Service

Returns a list of all products that match the filter criteria.

Request Syntax
{
"Filters": [
{
"Field": "string",
"Type": "string",
"Value": "string"
}
],
"FormatVersion": "string",
"MaxResults": number,
"NextToken": "string",
"ServiceCode": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 53).

The request accepts the following data in JSON format.

Filters (p. 32)

The list of filters that limit the returned products. only products that match all filters are returned.

Type: Array of Filter (p. 51) objects

Required: No
FormatVersion (p. 32)

The format version that you want the response to be in.

Valid values are: aws_v1

Type: String

Required: No
MaxResults (p. 32)

The maximum number of results to return in the response.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No
NextToken (p. 32)

The pagination token that indicates the next set of results that you want to retrieve.

Type: String

32
 AWS Cost Explorer Service Cost Management APIs
GetProducts

Required: No
ServiceCode (p. 32)

The code for the service whose products you want to retrieve.

Type: String

Required: No

Response Syntax
{
"FormatVersion": "string",
"NextToken": "string",
"PriceList": [ "string" ]
}

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.

FormatVersion (p. 33)

The format version of the response. For example, aws_v1.

Type: String
NextToken (p. 33)

The pagination token that indicates the next set of results to retrieve.

Type: String
PriceList (p. 33)

The list of products that match your filters. The list contains both the product metadata and the
price information.

Type: Array of strings

Errors
For information about the errors that are common to all actions, see Common Errors (p. 55).

ExpiredNextTokenException

The pagination token expired. Try again without a pagination token.

HTTP Status Code: 400

InternalErrorException

An error on the server occurred during the processing of your request. Try again later.

HTTP Status Code: 400

InvalidNextTokenException

The pagination token is invalid. Try again without a pagination token.

33
 AWS Cost Explorer Service Cost Management APIs
GetProducts

HTTP Status Code: 400

InvalidParameterException

One or more parameters had an invalid value.

HTTP Status Code: 400

NotFoundException

The requested resource can't be found.

HTTP Status Code: 400

Example
The following is a sample request and response of the GetProducts operation.
Sample Request

POST / HTTP/1.1
Host: api.pricing.<region>.<domain>
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: AWSPriceListService.GetProducts
{
"Filters": [
{
"Type": "TERM_MATCH",
"Field": "ServiceCode",
"Value": "AmazonEC2"
},
{
"Type": "TERM_MATCH",
"Field": "volumeType",
"Value": "Provisioned IOPS"
}
],
"FormatVersion": "aws_v1",
"NextToken": null,
"MaxResults": 1
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
Content-Type: application/x-amz-json-1.1
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
"FormatVersion": "aws_v1",
"NextToken": "57r3UcqRjDujbzWfHF7Ciw==:ywSmZsD3mtpQmQLQ5XfOsIMkYybSj
+vAT+kGmwMFq+K9DGmIoJkz7lunVeamiOPgthdWSO2a7YKojCO+zY4dJmuNl2QvbNhXs
+AJ2Ufn7xGmJncNI2TsEuAsVCUfTAvAQNcwwamtk6XuZ4YdNnooV62FjkV3ZAn40d9+wAxV7+FImvhUHi/
+f8afgZdGh2zPUlH8jlV9uUtj0oHp8+DhPUuHXh+WBII1E/aoKpPSm3c=",

34
 AWS Cost Explorer Service Cost Management APIs
GetProducts

"PriceList": [
"{\"product\":{\"productFamily\":\"Storage\",\"attributes\":{\"storageMedia
\":\"SSD-backed\",\"maxThroughputvolume\":\"320 MB/sec\",\"volumeType\":\"Provisioned
IOPS\",\"maxIopsvolume\":\"20000\",\"servicecode\":\"AmazonEC2\",\"usagetype\":
\"CAN1-EBS:VolumeUsage.piops\",\"locationType\":\"AWS Region\",\"location\":\"Canada
(Central)\",\"servicename\":\"Amazon Elastic Compute Cloud\",\"maxVolumeSize
\":\"16 TiB\",\"operation\":\"\"},\"sku\":\"WQGC34PB2AWS8R4U\"},\"serviceCode
\":\"AmazonEC2\",\"terms\":{\"OnDemand\":{\"WQGC34PB2AWS8R4U.JRTCKXETXF\":
{\"priceDimensions\":{\"WQGC34PB2AWS8R4U.JRTCKXETXF.6YS6EN2CT7\":{\"unit\":\"GB-Mo
\",\"endRange\":\"Inf\",\"description\":\"$0.138 per GB-month of Provisioned IOPS
SSD (io1) provisioned storage - Canada (Central)\",\"appliesTo\":[],\"rateCode
\":\"WQGC34PB2AWS8R4U.JRTCKXETXF.6YS6EN2CT7\",\"beginRange\":\"0\",\"pricePerUnit
\":{\"USD\":\"0.1380000000\"}}},\"sku\":\"WQGC34PB2AWS8R4U\",\"effectiveDate\":
\"2017-08-01T00:00:00Z\",\"offerTermCode\":\"JRTCKXETXF\",\"termAttributes\":{}}}},
\"version\":\"20170901182201\",\"publicationDate\":\"2017-09-01T18:22:01Z\"}"
]
}

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

35
 AWS Cost Explorer Service Cost Management APIs
AWS Cost Explorer Service

Data Types
The following data types are supported by AWS Cost Explorer Service:

• DateInterval (p. 37)

• DimensionValues (p. 38)
• DimensionValuesWithAttributes (p. 39)
• Expression (p. 40)
• Group (p. 42)
• GroupDefinition (p. 43)
• MetricValue (p. 44)
• ReservationAggregates (p. 45)
• ReservationUtilizationGroup (p. 46)
• ResultByTime (p. 47)
• TagValues (p. 48)
• UtilizationByTime (p. 49)

The following data types are supported by AWS Price List Service:

• AttributeValue (p. 50)

• Filter (p. 51)
• Service (p. 52)

AWS Cost Explorer Service

The following data types are supported by AWS Cost Explorer Service:

• DateInterval (p. 37)

• DimensionValues (p. 38)
• DimensionValuesWithAttributes (p. 39)
• Expression (p. 40)
• Group (p. 42)
• GroupDefinition (p. 43)
• MetricValue (p. 44)
• ReservationAggregates (p. 45)
• ReservationUtilizationGroup (p. 46)
• ResultByTime (p. 47)
• TagValues (p. 48)
• UtilizationByTime (p. 49)

36
 AWS Cost Explorer Service Cost Management APIs
DateInterval

DateInterval
Service: AWS Cost Explorer Service

The time period that you want the usage and costs for.

Contents
End

The end of the time period that you want the usage and costs for. The end date is exclusive. For
example, if the end is 2017-05-01, then the cost and usage data is retrieved from the start date but
not including 2017-05-01.

Type: String

Pattern: \d{4}-\d{2}-\d{2}

Required: Yes
Start

The beginning of the time period that you want the usage and costs for. The start date is inclusive.
For example, if start is 2017-01-01, then the cost and usage data is retrieved starting at
2017-01-01 up to the end date.

Type: String

Pattern: \d{4}-\d{2}-\d{2}

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

37
 AWS Cost Explorer Service Cost Management APIs
DimensionValues

DimensionValues
Service: AWS Cost Explorer Service

The metadata that you can use to filter and group your results. You can use GetDimensionValues to
find specific values.

Contents
Key

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.

Type: String

Valid Values: AZ | INSTANCE_TYPE | LINKED_ACCOUNT | OPERATION | PURCHASE_TYPE

| REGION | SERVICE | USAGE_TYPE | USAGE_TYPE_GROUP | RECORD_TYPE |
OPERATING_SYSTEM | TENANCY | SCOPE | PLATFORM | SUBSCRIPTION_ID

Required: No
Values

The metadata values that you can use to filter and group your results. You can use
GetDimensionValues to find specific values.

Type: Array of strings

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

38
 AWS Cost Explorer Service Cost Management APIs
DimensionValuesWithAttributes

DimensionValuesWithAttributes
Service: AWS Cost Explorer Service

The metadata of a specific type that you can use to filter and group your results. You can use
GetDimensionValues to find specific values.

Contents
Attributes

The attribute that applies to a specific Dimension.

Type: String to string map

Required: No
Value

The value of a dimension with a specific attribute.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

39
 AWS Cost Explorer Service Cost Management APIs
Expression

Expression
Service: AWS Cost Explorer Service

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 INSTANCE_TYPE==m4.xlarge OR
INSTANCE_TYPE==c4.large. The Expression for that looks like this.

{ "Dimensions": { "Key": "INSTANCE_TYPE", "Values": [ "m4.xlarge",

“c4.large” ] } }

The list of dimension values are OR'd together to retrieve cost or usage data. You can create
Expression and DimensionValues objects using either with* methods or set* methods in
multiple lines.
• Compound dimension values with logical operations - You can use multiple Expression types and
the logical operators AND/OR/NOT to create a list of one or more Expression objects. This allows you
to filter on more advanced options. For example, you can filter on ((INSTANCE_TYPE == m4.large
OR INSTANCE_TYPE == m3.large) OR (TAG.Type == Type1)) AND (USAGE_TYPE !=
DataTransfer). The Expression for that looks like this.

{ "And": [ {"Or": [ {"Dimensions": { "Key": "INSTANCE_TYPE", "Values":

[ "m4.x.large", "c4.large" ] }}, {"Tag": { "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 an Expression object that will create an
error.

{ "And": [ ... ], "DimensionValues": { "Dimension": "USAGE_TYPE", "Values":

[ "DataTransfer" ] } }

Contents
And

Return results that match both Dimension objects.

Type: Array of Expression (p. 40) objects

Required: No
Dimensions

The specific Dimension to use for Expression.

Type: DimensionValues (p. 38) object

Required: No
Not

Return results that don't match Dimension.

Type: Expression (p. 40) object

Required: No

40
 AWS Cost Explorer Service Cost Management APIs
Expression

Or

Return results that match either Dimension.

Type: Array of Expression (p. 40) objects

Required: No
Tags

The specific Tag to use for Expression.

Type: TagValues (p. 48) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

41
 AWS Cost Explorer Service Cost Management APIs
Group

Group
Service: AWS Cost Explorer Service

One level of grouped data within the results.

Contents
Keys

The keys included in this group.

Type: Array of strings

Required: No
Metrics

The metrics included in this group.

Type: String to MetricValue (p. 44) object map

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

42
 AWS Cost Explorer Service Cost Management APIs
GroupDefinition

GroupDefinition
Service: AWS Cost Explorer Service

Represents a group when you specify a group by criteria, or in the response to a query with a specific
grouping.

Contents
Key

The string that represents a key for a specified group.

Type: String

Required: No
Type

The string that represents the type of group.

Type: String

Valid Values: DIMENSION | TAG

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

43
 AWS Cost Explorer Service Cost Management APIs
MetricValue

MetricValue
Service: AWS Cost Explorer Service

The aggregated value for a metric.

Contents
Amount

The actual number that represents the metric.

Type: String

Required: No
Unit

The unit that the metric is given in.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

44
 AWS Cost Explorer Service Cost Management APIs
ReservationAggregates

ReservationAggregates
Service: AWS Cost Explorer Service

The aggregated numbers for your RI usage.

Contents
PurchasedHours

How many RI hours you purchased.

Type: String

Required: No
TotalActualHours

The total number of RI hours that you used.

Type: String

Required: No
UnusedHours

The number of RI hours that you didn't use.

Type: String

Required: No
UtilizationPercentage

The percentage of RI time that you used.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

45
 AWS Cost Explorer Service Cost Management APIs
ReservationUtilizationGroup

ReservationUtilizationGroup
Service: AWS Cost Explorer Service

A group of RIs that share a set of attributes.

Contents
Attributes

The attributes for this group of RIs.

Type: String to string map

Required: No
Key

The key for a specific RI attribute.

Type: String

Required: No
Utilization

How much you used this group of RIs.

Type: ReservationAggregates (p. 45) object

Required: No
Value

The value of a specific RI attribute.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

46
 AWS Cost Explorer Service Cost Management APIs
ResultByTime

ResultByTime
Service: AWS Cost Explorer Service

The result that is associated with a time period.

Contents
Estimated

Whether or not this result is estimated.

Type: Boolean

Required: No
Groups

The groups that are included in this time period.

Type: Array of Group (p. 42) objects

Required: No
TimePeriod

The time period covered by a result.

Type: DateInterval (p. 37) object

Required: No
Total

The total amount of cost or usage accrued during the time period.

Type: String to MetricValue (p. 44) object map

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

47
 AWS Cost Explorer Service Cost Management APIs
TagValues

TagValues
Service: AWS Cost Explorer Service

The values that are available for a tag.

Contents
Key

The key for a tag.

Type: String

Required: No
Values

The specific value of a tag.

Type: Array of strings

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

48
 AWS Cost Explorer Service Cost Management APIs
UtilizationByTime

UtilizationByTime
Service: AWS Cost Explorer Service

The amount of utilization, in hours.

Contents
Groups

The groups that are included in this utilization result.

Type: Array of ReservationUtilizationGroup (p. 46) objects

Required: No
TimePeriod

The period of time over which this utilization was used.

Type: DateInterval (p. 37) object

Required: No
Total

The total number of RI hours that were used.

Type: ReservationAggregates (p. 45) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

AWS Price List Service

The following data types are supported by AWS Price List Service:

• AttributeValue (p. 50)

• Filter (p. 51)
• Service (p. 52)

49
 AWS Cost Explorer Service Cost Management APIs
AttributeValue

AttributeValue
Service: AWS Price List Service

The values of a given attribute, such as Throughput Optimized HDD or Provisioned IOPS for the
Amazon EC2 volumeType attribute.

Contents
Value

The specific value of an attributeName.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

50
 AWS Cost Explorer Service Cost Management APIs
Filter

Filter
Service: AWS Price List Service

The constraints that you want all returned products to match.

Contents
Field

The product metadata field that you want to filter on. You can filter by just the service code to see
all products for a specific service, filter by just the attribute name to see a specific attribute for
multiple services, or use both a service code and an attribute name to retrieve only products that
match both fields.

Valid values include: ServiceCode, and all attribute names

For example, you can filter by the AmazonEC2 service code and the volumeType attribute name to
get the prices for only Amazon EC2 volumes.

Type: String

Required: Yes
Type

The type of filter that you want to use.

Valid values are: TERM_MATCH. TERM_MATCH returns only products that match both the given filter
field and the given value.

Type: String

Valid Values: TERM_MATCH

Required: Yes
Value

The service code or attribute value that you want to filter by. If you are filtering by service code
this is the actual service code, such as AmazonEC2. If you are filtering by attribute name, this is
the attribute value that you want the returned products to match, such as a Provisioned IOPS
volume.

Type: String

Required: Yes

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

51
 AWS Cost Explorer Service Cost Management APIs
Service

Service
Service: AWS Price List Service

The metadata for a service, such as the service code and available attribute names.

Contents
AttributeNames

The attributes that are available for this service.

Type: Array of strings

Required: No
ServiceCode

The code for the AWS service.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

52
 AWS Cost Explorer Service Cost Management APIs

Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests
with a query string. Any action-specific parameters are listed in the topic for that action. For more
information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web
Services General Reference.

Action

The action to be performed.

Type: string

Required: Yes
Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string

Required: Yes
X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: Conditional
X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is

53
 AWS Cost Explorer Service Cost Management APIs

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For
more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General
Reference.

Type: string

Required: Conditional
X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.

Type: string

Required: Conditional
X-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional

54
 AWS Cost Explorer Service Cost Management APIs

Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an API
action for this service, see the topic for that API action.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400

IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400

InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400

InvalidClientTokenId

The X.509 certificate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403

InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400

InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400

InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400

MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404

MissingAction

The request is missing an action or a required parameter.

HTTP Status Code: 400

55
 AWS Cost Explorer Service Cost Management APIs

MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certificate.

HTTP Status Code: 403

MissingParameter

A required parameter for the specified action is not supplied.

HTTP Status Code: 400

OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403

RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more
than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp
on the request is more than 15 minutes in the future.

HTTP Status Code: 400

ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400

ValidationError

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

56