GetCostAndUsage
Retrieves cost and usage metrics for your account. You can specify which cost and
usage-related metric that you want the request to return. For example, you can specify
BlendedCosts
or UsageQuantity
. You can also filter and group your
data by various dimensions, such as SERVICE
or AZ
, in a specific
time range. For a complete list of valid dimensions, see the GetDimensionValues operation. Management account in an organization in AWS Organizations have access to all member accounts.
For information about filter limitations, see Quotas and restrictions in the Billing and Cost Management User Guide.
Request Syntax
{
"Filter": {
"And": [
"Expression"
],
"CostCategories": {
"Key": "string
",
"MatchOptions": [ "string
" ],
"Values": [ "string
" ]
},
"Dimensions": {
"Key": "string
",
"MatchOptions": [ "string
" ],
"Values": [ "string
" ]
},
"Not": "Expression",
"Or": [
"Expression"
],
"Tags": {
"Key": "string
",
"MatchOptions": [ "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.
The request accepts the following data in JSON format.
- Filter
-
Filters AWS costs by different dimensions. For example, you can specify
SERVICE
andLINKED_ACCOUNT
and get the costs that are associated with that account's usage of that service. You can nestExpression
objects to define any combination of dimension filters. For more information, see Expression.Valid values for
MatchOptions
forDimensions
areEQUALS
andCASE_SENSITIVE
.Valid values for
MatchOptions
forCostCategories
andTags
areEQUALS
,ABSENT
, andCASE_SENSITIVE
. Default values areEQUALS
andCASE_SENSITIVE
.Type: Expression object
Required: No
- Granularity
-
Sets the AWS cost granularity to
MONTHLY
orDAILY
, orHOURLY
. IfGranularity
isn't set, the response object doesn't include theGranularity
, eitherMONTHLY
orDAILY
, orHOURLY
.Type: String
Valid Values:
DAILY | MONTHLY | HOURLY
Required: Yes
- GroupBy
-
You can group AWS costs using up to two different groups, either dimensions, tag keys, cost categories, or any two group by types.
Valid values for the
DIMENSION
type areAZ
,INSTANCE_TYPE
,LEGAL_ENTITY_NAME
,INVOICING_ENTITY
,LINKED_ACCOUNT
,OPERATION
,PLATFORM
,PURCHASE_TYPE
,SERVICE
,TENANCY
,RECORD_TYPE
, andUSAGE_TYPE
.When you group by the
TAG
type and include a valid tag key, you get all tag values, including empty strings.Type: Array of GroupDefinition objects
Required: No
- Metrics
-
Which metrics are returned in the query. For more information about blended and unblended rates, see Why does the "blended" annotation appear on some line items in my bill?
. Valid values are
AmortizedCost
,BlendedCost
,NetAmortizedCost
,NetUnblendedCost
,NormalizedUsageAmount
,UnblendedCost
, andUsageQuantity
.Note
If you return the
UsageQuantity
metric, the service aggregates all usage numbers without taking into account the units. For example, if you aggregateusageQuantity
across all of Amazon EC2, the results aren't meaningful because Amazon EC2 compute hours and data transfer are measured in different units (for example, hours and GB). To get more meaningfulUsageQuantity
metrics, filter byUsageType
orUsageTypeGroups
.Metrics
is required forGetCostAndUsage
requests.Type: Array of strings
Length Constraints: Minimum length of 0. Maximum length of 1024.
Pattern:
[\S\s]*
Required: Yes
- 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
- TimePeriod
-
Sets the start date and end date for retrieving AWS costs. The start date is inclusive, but the end date is exclusive. For example, if
start
is2017-01-01
andend
is2017-05-01
, then the cost and usage data is retrieved from2017-01-01
up to and including2017-04-30
but not including2017-05-01
.Type: DateInterval object
Required: Yes
Response Syntax
{
"DimensionValueAttributes": [
{
"Attributes": {
"string" : "string"
},
"Value": "string"
}
],
"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.
- DimensionValueAttributes
-
The attributes that apply to a specific dimension value. For example, if the value is a linked account, the attribute is that account name.
Type: Array of DimensionValuesWithAttributes objects
- GroupDefinitions
-
The groups that are specified by the
Filter
orGroupBy
parameters in the request.Type: Array of GroupDefinition 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]*
- ResultsByTime
-
The time period that's covered by the results in the response.
Type: Array of ResultByTime objects
Errors
For information about the errors that are common to all actions, see Common Errors.
- BillExpirationException
-
The requested report expired. Update the date interval and try again.
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
Examples
Example
The following is a sample request and response of the GetCostAndUsage
operation that you can use to retrieve your Amazon S3 costs. For more complex examples,
such as multi-level groupings, see Expression.
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.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
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": {}
}
]
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: