AWS Billing and Cost Management API Reference

(1)

AWS Billing and Cost Management

API Reference

AWS Billing and Cost Management: API Reference

(2)

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 aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

AWS Cost Explorer

You can use the Cost Explorer API 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. This might include the number of daily write operations for Amazon DynamoDB database tables in your production environment.

Service Endpoint

The Cost Explorer API provides the following endpoint:

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

For information about the costs that are associated with the Cost Explorer API, see AWS Cost Management Pricing.

AWS Budgets

The AWS Budgets API enables you to use AWS Budgets to plan your service usage, service costs, and instance reservations. The API reference provides descriptions, syntax, and usage examples for each of the actions and data types for AWS Budgets.

Budgets provide you with a way to see the following information:

• How close your plan is to your budgeted amount or to the free tier limits

• Your usage-to-date, including how much you've used of your Reserved Instances (RIs)

• Your current estimated charges from AWS, and how much your predicted usage will accrue in charges by the end of the month

• How much of your budget has been used

AWS updates your budget status several times a day. Budgets track your unblended costs, subscriptions, refunds, and RIs. You can create the following types of budgets:

• Cost budgets - Plan how much you want to spend on a service.

• Usage budgets - Plan how much you want to use one or more services.

• RI utilization budgets - Deﬁne a utilization threshold, and receive alerts when your RI usage falls below that threshold. This lets you see if your RIs are unused or under-utilized.

• RI coverage budgets - Deﬁne a coverage threshold, and receive alerts when the number of your instance hours that are covered by RIs fall below that threshold. This lets you see how much of your instance usage is covered by a reservation.

Service Endpoint

The AWS Budgets API provides the following endpoint:

• https://budgets.amazonaws.com

(8)

AWS Cost and Usage Report

For information about costs that are associated with the AWS Budgets API, see AWS Cost Management Pricing.

AWS Cost and Usage Report

The AWS Cost and Usage Report API enables you to programmatically create, query, and delete AWS Cost and Usage report deﬁnitions.

AWS Cost and Usage reports track the monthly AWS costs and usage associated with your AWS account.

The report contains line items for each unique combination of AWS product, usage type, and operation that your AWS account uses. You can conﬁgure the AWS Cost and Usage report to show only the data that you want, using the AWS Cost and Usage API.

Service Endpoint

The AWS Cost and Usage Report API provides the following endpoint:

• cur.us-east-1.amazonaws.com

AWS Price List

AWS Price List Service API (AWS Price List Service) is a centralized and convenient way to

programmatically query AWS 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 beneﬁt 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 ﬁnd speciﬁc 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

(9)

Actions

The following actions are supported by AWS Cost Explorer:

• CreateAnomalyMonitor (p. 6)

• CreateAnomalySubscription (p. 8)

• CreateCostCategoryDeﬁnition (p. 10)

• DeleteAnomalyMonitor (p. 14)

• DeleteAnomalySubscription (p. 16)

• DeleteCostCategoryDeﬁnition (p. 18)

• DescribeCostCategoryDeﬁnition (p. 20)

• GetAnomalies (p. 23)

• GetAnomalyMonitors (p. 26)

• GetAnomalySubscriptions (p. 29)

• GetCostAndUsage (p. 32)

• GetCostAndUsageWithResources (p. 39)

• GetCostCategories (p. 46)

• GetCostForecast (p. 51)

• GetDimensionValues (p. 56)

• GetReservationCoverage (p. 65)

• GetReservationPurchaseRecommendation (p. 73)

• GetReservationUtilization (p. 79)

• GetRightsizingRecommendation (p. 87)

• GetSavingsPlansCoverage (p. 93)

• GetSavingsPlansPurchaseRecommendation (p. 98)

• GetSavingsPlansUtilization (p. 103)

• GetSavingsPlansUtilizationDetails (p. 107)

• GetTags (p. 112)

• GetUsageForecast (p. 118)

• ListCostCategoryDeﬁnitions (p. 123)

• ProvideAnomalyFeedback (p. 126)

• UpdateAnomalyMonitor (p. 128)

• UpdateAnomalySubscription (p. 130)

• UpdateCostCategoryDeﬁnition (p. 133)

The following actions are supported by AWS Budgets:

• CreateBudget (p. 137)

• CreateBudgetAction (p. 145)

• CreateNotiﬁcation (p. 149)

• CreateSubscriber (p. 152)

• DeleteBudget (p. 155)

• DeleteBudgetAction (p. 157)

• DeleteNotiﬁcation (p. 160)

(10)

AWS Cost Explorer

• DeleteSubscriber (p. 163)

• DescribeBudget (p. 166)

• DescribeBudgetAction (p. 173)

• DescribeBudgetActionHistories (p. 176)

• DescribeBudgetActionsForAccount (p. 180)

• DescribeBudgetActionsForBudget (p. 183)

• DescribeBudgetNotiﬁcationsForAccount (p. 186)

• DescribeBudgetPerformanceHistory (p. 189)

• DescribeBudgets (p. 194)

• DescribeNotiﬁcationsForBudget (p. 201)

• DescribeSubscribersForNotiﬁcation (p. 205)

• ExecuteBudgetAction (p. 209)

• UpdateBudget (p. 212)

• UpdateBudgetAction (p. 219)

• UpdateNotiﬁcation (p. 224)

• UpdateSubscriber (p. 227)

The following actions are supported by AWS Cost and Usage Report:

• DeleteReportDeﬁnition (p. 230)

• DescribeReportDeﬁnitions (p. 232)

• ModifyReportDeﬁnition (p. 235)

• PutReportDeﬁnition (p. 237)

The following actions are supported by AWS Price List:

• DescribeServices (p. 240)

• GetAttributeValues (p. 244)

• GetProducts (p. 248)

AWS Cost Explorer

The following actions are supported by AWS Cost Explorer:

• CreateAnomalyMonitor (p. 6)

• CreateAnomalySubscription (p. 8)

• CreateCostCategoryDeﬁnition (p. 10)

• DeleteAnomalyMonitor (p. 14)

• DeleteAnomalySubscription (p. 16)

• DeleteCostCategoryDeﬁnition (p. 18)

• DescribeCostCategoryDeﬁnition (p. 20)

• GetAnomalies (p. 23)

• GetAnomalyMonitors (p. 26)

• GetAnomalySubscriptions (p. 29)

• GetCostAndUsage (p. 32)

• GetCostAndUsageWithResources (p. 39)

(11)

AWS Cost Explorer

• GetCostCategories (p. 46)

• GetCostForecast (p. 51)

• GetDimensionValues (p. 56)

• GetReservationCoverage (p. 65)

• GetReservationPurchaseRecommendation (p. 73)

• GetReservationUtilization (p. 79)

• GetRightsizingRecommendation (p. 87)

• GetSavingsPlansCoverage (p. 93)

• GetSavingsPlansPurchaseRecommendation (p. 98)

• GetSavingsPlansUtilization (p. 103)

• GetSavingsPlansUtilizationDetails (p. 107)

• GetTags (p. 112)

• GetUsageForecast (p. 118)

• ListCostCategoryDeﬁnitions (p. 123)

• ProvideAnomalyFeedback (p. 126)

• UpdateAnomalyMonitor (p. 128)

• UpdateAnomalySubscription (p. 130)

• UpdateCostCategoryDeﬁnition (p. 133)

(12)

CreateAnomalyMonitor

Service: AWS Cost Explorer

Creates a new cost anomaly detection monitor with the requested type and monitor speciﬁcation.

Request Syntax

{ "AnomalyMonitor": {

"CreationDate": "string",

"DimensionalValueCount": number, "LastEvaluatedDate": "string", "LastUpdatedDate": "string", "MonitorArn": "string", "MonitorDimension": "string", "MonitorName": "string", "MonitorSpecification": { "And": [

"Expression"

],

"CostCategories": { "Key": "string",

"MatchOptions": [ "string" ], "Values": [ "string" ] },

"Dimensions": { "Key": "string",

"Not": "Expression", "Or": [

"Expression"

],

"Tags": {

"Key": "string",

"MatchOptions": [ "string" ], "Values": [ "string" ] }

},

"MonitorType": "string"

}}

Request Parameters

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

The request accepts the following data in JSON format.

AnomalyMonitor (p. 6)

The cost anomaly detection monitor object that you want to create.

Type: AnomalyMonitor (p. 260) object Required: Yes

(13)

CreateAnomalyMonitor

Response Syntax

{ "MonitorArn": "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.

MonitorArn (p. 7)

The unique identiﬁer of your newly created cost anomaly detection monitor.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Pattern: [\S\s]*

Errors

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

LimitExceededException

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

HTTP Status Code: 400

CreateAnomalySubscription

Adds a subscription to a cost anomaly detection monitor. You can use each subscription to define subscribers with email or SNS notifications. Email subscribers can set a dollar threshold and a time frequency for receiving notifications.

Request Syntax

{ "AnomalySubscription": { "AccountId": "string", "Frequency": "string",

"MonitorArnList": [ "string" ], "Subscribers": [

{

"Address": "string", "Status": "string", "Type": "string"

} ],

"SubscriptionArn": "string", "SubscriptionName": "string", "Threshold": number

}}

Request Parameters

AnomalySubscription (p. 8)

The cost anomaly subscription object that you want to create.

Type: AnomalySubscription (p. 264) object Required: Yes

Response Syntax

{

"SubscriptionArn": "string"

}

Response Elements

SubscriptionArn (p. 8)

The unique identiﬁer of your newly created cost anomaly subscription.

(15)

CreateAnomalySubscription

Type: String

Pattern: [\S\s]*

Errors

HTTP Status Code: 400 UnknownMonitorException

The cost anomaly monitor does not exist for the account.

CreateCostCategoryDeﬁnition

Creates a new Cost Category with the requested name and rules.

Request Syntax

{ "DefaultValue": "string", "Name": "string",

"Rules": [ {

"InheritedValue": {

"DimensionKey": "string", "DimensionName": "string"

},

"Rule": { "And": [ "Expression"

],

"MatchOptions": [ "string" ], "Values": [ "string" ]

},

"Expression"

],

"Tags": {

"Key": "string",

} },

"Type": "string", "Value": "string"

} ],

"RuleVersion": "string", "SplitChargeRules": [ {

"Method": "string", "Parameters": [ {

"Type": "string", "Values": [ "string" ] }

],

"Source": "string", "Targets": [ "string" ] }

]}

(17)

Request Parameters

DefaultValue (p. 10)

The default value for the cost category.

Type: String

Pattern: ^(?! )[\p{L}\p{N}\p{Z}-_]*(?<! )$

Required: No Name (p. 10)

The unique name of the Cost Category.

Type: String

Pattern: ^(?! )[\p{L}\p{N}\p{Z}-_]*(?<! )$

Required: Yes Rules (p. 10)

The Cost Category rules used to categorize costs. For more information, see CostCategoryRule.

Type: Array of CostCategoryRule (p. 272) objects

Array Members: Minimum number of 1 item. Maximum number of 500 items.

Required: Yes RuleVersion (p. 10)

The rule schema version in this particular Cost Category.

Type: String

Valid Values: CostCategoryExpression.v1 Required: Yes

SplitChargeRules (p. 10)

The split charge rules used to allocate your charges between your Cost Category values.

Type: Array of CostCategorySplitChargeRule (p. 274) objects

Array Members: Minimum number of 1 item. Maximum number of 10 items.

Required: No

Response Syntax

{

(18)

"CostCategoryArn": "string", "EffectiveStart": "string"

}

Response Elements

CostCategoryArn (p. 11)

The unique identiﬁer for your newly created Cost Category.

Type: String

Pattern: arn:aws[-a-z0-9]*:[a-z0-9]+:[-a-z0-9]*:[0-9]{12}:[-a-zA-Z0-9/:_]+

EﬀectiveStart (p. 11)

The Cost Category's eﬀective start date.

Type: String

Pattern: ^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(([+-]\d\d:\d\d)|Z)$

Errors

HTTP Status Code: 400 ServiceQuotaExceededException

You've reached the limit on the number of resources you can create, or exceeded the size of an individual resource.

DeleteAnomalyMonitor

Service: AWS Cost Explorer Deletes a cost anomaly monitor.

Request Syntax

{ "MonitorArn": "string"

}

Request Parameters

MonitorArn (p. 14)

The unique identiﬁer of the cost anomaly monitor that you want to delete.

Type: String

Pattern: [\S\s]*

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

DeleteAnomalySubscription

Deletes a cost anomaly subscription.

Request Syntax

{ "SubscriptionArn": "string"

}

Request Parameters

SubscriptionArn (p. 16)

The unique identiﬁer of the cost anomaly subscription that you want to delete.

Type: String

Pattern: [\S\s]*

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

HTTP Status Code: 400 UnknownSubscriptionException

The cost anomaly subscription does not exist for the account.

DeleteCostCategoryDeﬁnition

Deletes a Cost Category. Expenses from this month going forward will no longer be categorized with this Cost Category.

Request Syntax

{ "CostCategoryArn": "string"

}

Request Parameters

The unique identiﬁer for your Cost Category.

Type: String

Required: Yes

Response Syntax

{ "CostCategoryArn": "string", "EffectiveEnd": "string"

}

Response Elements

Type: String

EﬀectiveEnd (p. 18)

The eﬀective end date of the Cost Category as a result of deleting it. No costs after this date will be categorized by the deleted Cost Category.

(25)

DeleteCostCategoryDeﬁnition

Type: String

Errors

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed ARN in the request doesn't exist.

DescribeCostCategoryDeﬁnition

Returns the name, ARN, rules, definition, and effective dates of a Cost Category that's defined in the account.

You have the option to use EffectiveOn to return a Cost Category that is active on a specific date. If there is no EffectiveOn specified, you’ll see a Cost Category that is effective on the current date. If Cost Category is still effective, EffectiveEnd is omitted in the response.

Request Syntax

{

"CostCategoryArn": "string", "EffectiveOn": "string"

}

Request Parameters

Type: String

Required: Yes EﬀectiveOn (p. 20)

The date when the Cost Category was eﬀective.

Type: String

Required: No

Response Syntax

{ "CostCategory": {

"CostCategoryArn": "string", "DefaultValue": "string", "EffectiveEnd": "string", "EffectiveStart": "string", "Name": "string",

"ProcessingStatus": [ {

"Component": "string",

(27)

"Status": "string"

} ],

"Rules": [ {

"InheritedValue": {

"DimensionKey": "string", "DimensionName": "string"

},

"Rule": { "And": [ "Expression"

],

"Expression"

],

"Tags": {

"Key": "string",

},

"Type": "string", "Value": "string"

} ],

"RuleVersion": "string", "SplitChargeRules": [ {

"Method": "string", "Parameters": [ {

"Type": "string", "Values": [ "string" ] }

],

"Source": "string", "Targets": [ "string" ] }

] }}

Response Elements

CostCategory (p. 20)

The structure of Cost Categories. This includes detailed metadata and the set of rules for the CostCategory object.

(28)

Type: CostCategory (p. 266) object

Errors

HTTP Status Code: 400 ResourceNotFoundException

The speciﬁed ARN in the request doesn't exist.

GetAnomalies

Retrieves all of the cost anomalies detected on your account during the time period that's speciﬁed by the DateInterval object.

Request Syntax

{ "DateInterval": { "EndDate": "string", "StartDate": "string"

},

"Feedback": "string", "MaxResults": number, "MonitorArn": "string", "NextPageToken": "string", "TotalImpact": {

"EndValue": number,

"NumericOperator": "string", "StartValue": number

}}

Request Parameters

DateInterval (p. 23)

Assigns the start and end dates for retrieving cost anomalies. The returned anomaly object will have an AnomalyEndDate in the speciﬁed time range.

Type: AnomalyDateInterval (p. 259) object Required: Yes

Feedback (p. 23)

Filters anomaly results by the feedback ﬁeld on the anomaly object.

Type: String

Valid Values: YES | NO | PLANNED_ACTIVITY Required: No

MaxResults (p. 23)

The number of entries a paginated response contains.

Type: Integer Required: No MonitorArn (p. 23)

Retrieves all of the cost anomalies detected for a speciﬁc cost anomaly monitor Amazon Resource Name (ARN).

(30)

GetAnomalies

Type: String

Pattern: [\S\s]*

Required: No NextPageToken (p. 23)

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

Pattern: [\S\s]*

Required: No TotalImpact (p. 23)

Filters anomaly results by the total impact ﬁeld on the anomaly object. For example, you can ﬁlter anomalies GREATER_THAN 200.00 to retrieve anomalies, with an estimated dollar impact greater than 200.

Type: TotalImpactFilter (p. 376) object Required: No

Response Syntax

{

"Anomalies": [ {

"AnomalyEndDate": "string", "AnomalyId": "string", "AnomalyScore": {

"CurrentScore": number, "MaxScore": number },

"AnomalyStartDate": "string", "DimensionValue": "string", "Feedback": "string", "Impact": {

"MaxImpact": number, "TotalImpact": number },

"MonitorArn": "string", "RootCauses": [ {

"LinkedAccount": "string", "Region": "string", "Service": "string", "UsageType": "string"

} ] } ],

"NextPageToken": "string"

}

(31)

GetAnomalies

Response Elements

Anomalies (p. 24)

A list of cost anomalies.

Type: Array of Anomaly (p. 257) objects NextPageToken (p. 24)

Type: String

Pattern: [\S\s]*

Errors

InvalidNextTokenException

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

HTTP Status Code: 400 LimitExceededException

GetAnomalyMonitors

Retrieves the cost anomaly monitor deﬁnitions for your account. You can ﬁlter using a list of cost anomaly monitor Amazon Resource Names (ARNs).

Request Syntax

{ "MaxResults": number,

"MonitorArnList": [ "string" ], "NextPageToken": "string"

}

Request Parameters

The number of entries that a paginated response contains.

Type: Integer Required: No MonitorArnList (p. 26)

A list of cost anomaly monitor ARNs.

Type: Array of strings

Pattern: [\S\s]*

Type: String

Pattern: [\S\s]*

Required: No

Response Syntax

{ "AnomalyMonitors": [ {

"CreationDate": "string",

(33)

GetAnomalyMonitors

"DimensionalValueCount": number, "LastEvaluatedDate": "string", "LastUpdatedDate": "string", "MonitorArn": "string", "MonitorDimension": "string", "MonitorName": "string", "MonitorSpecification": { "And": [

"Expression"

],

"Expression"

],

"Tags": {

"Key": "string",

},

"MonitorType": "string"

} ],

}

Response Elements

AnomalyMonitors (p. 26)

A list of cost anomaly monitors that includes the detailed metadata for each monitor.

Type: Array of AnomalyMonitor (p. 260) objects NextPageToken (p. 26)

Type: String

Pattern: [\S\s]*

Errors

(34)

GetAnomalyMonitors

GetAnomalySubscriptions

Retrieves the cost anomaly subscription objects for your account. You can ﬁlter using a list of cost anomaly monitor Amazon Resource Names (ARNs).

Request Syntax

{

"MaxResults": number, "MonitorArn": "string", "NextPageToken": "string",

"SubscriptionArnList": [ "string" ] }

Request Parameters

The number of entries a paginated response contains.

Type: Integer Required: No MonitorArn (p. 29)

Cost anomaly monitor ARNs.

Type: String

Pattern: [\S\s]*

Type: String

Pattern: [\S\s]*

Required: No

SubscriptionArnList (p. 29)

A list of cost anomaly subscription ARNs.

(36)

Pattern: [\S\s]*

Required: No

Response Syntax

{

"AnomalySubscriptions": [ {

"AccountId": "string", "Frequency": "string",

"MonitorArnList": [ "string" ], "Subscribers": [

{

"Address": "string", "Status": "string", "Type": "string"

} ],

"SubscriptionArn": "string", "SubscriptionName": "string", "Threshold": number

} ],

}

Response Elements

AnomalySubscriptions (p. 30)

A list of cost anomaly subscriptions that includes the detailed metadata for each one.

Type: Array of AnomalySubscription (p. 264) objects NextPageToken (p. 30)

Type: String

Pattern: [\S\s]*

Errors

(37)

HTTP Status Code: 400 UnknownSubscriptionException

The cost anomaly subscription does not exist for the account.

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 ﬁlter and group your data by various dimensions, such as SERVICE or AZ, in a speciﬁc 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 ﬁlter limitations, see Quotas and restrictions in the Billing and Cost Management User Guide.

Request Syntax

{ "Filter": { "And": [ "Expression"

],

"Expression"

],

"Tags": {

"Key": "string",

},

"Granularity": "string", "GroupBy": [

{

"Key": "string", "Type": "string"

} ],

"Metrics": [ "string" ], "NextPageToken": "string", "TimePeriod": {

"End": "string", "Start": "string"

} }

Request Parameters

(39)

GetCostAndUsage

Filter (p. 32)

Filters AWS costs by diﬀerent dimensions. For example, you can specify SERVICE and

LINKED_ACCOUNT and get the costs that are associated with that account's usage of that service.

You can nest Expression objects to deﬁne any combination of dimension ﬁlters. For more information, see Expression.

Valid values for MatchOptions for Dimensions are EQUALS and CASE_SENSITIVE.

Valid values for MatchOptions for CostCategories and Tags are EQUALS, ABSENT, and CASE_SENSITIVE. Default values are EQUALS and CASE_SENSITIVE.

Type: Expression (p. 305) object Required: No

Granularity (p. 32)

Sets the AWS cost granularity to MONTHLY or DAILY, or HOURLY. If Granularity isn't set, the response object doesn't include the Granularity, either MONTHLY or DAILY, or HOURLY.

Type: String

Valid Values: DAILY | MONTHLY | HOURLY Required: Yes

GroupBy (p. 32)

You can group AWS costs using up to two diﬀerent groups, either dimensions, tag keys, cost categories, or any two group by types.

Valid values for the DIMENSION type are AZ, INSTANCE_TYPE, LEGAL_ENTITY_NAME,

INVOICING_ENTITY, LINKED_ACCOUNT, OPERATION, PLATFORM, PURCHASE_TYPE, SERVICE, TENANCY, RECORD_TYPE, and USAGE_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 GroupDeﬁnition (p. 310) objects Required: No

Metrics (p. 32)

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, 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 Amazon EC2, the results aren't meaningful because Amazon EC2 compute hours and data transfer are measured in diﬀerent units (for example, hours and GB). To get more meaningful UsageQuantity metrics, ﬁlter by UsageType or UsageTypeGroups.

Metrics is required for GetCostAndUsage requests.

Pattern: [\S\s]*

Required: Yes

(40)

GetCostAndUsage

NextPageToken (p. 32)

Type: String

Pattern: [\S\s]*

Required: No TimePeriod (p. 32)

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 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. 286) object Required: Yes

Response Syntax

{

"DimensionValueAttributes": [ {

"Attributes": { "string" : "string"

},

"Value": "string"

} ],

"GroupDefinitions": [ {

} ],

"NextPageToken": "string", "ResultsByTime": [ {

"Estimated": boolean, "Groups": [

{

"Keys": [ "string" ], "Metrics": {

"string" : {

"Amount": "string", "Unit": "string"

} } } ],

"TimePeriod": { "End": "string", "Start": "string"

},

"Total": { "string" : {

(41)

GetCostAndUsage

} } } ] }

Response Elements

DimensionValueAttributes (p. 34)

The attributes that apply to a speciﬁc dimension value. For example, if the value is a linked account, the attribute is that account name.

Type: Array of DimensionValuesWithAttributes (p. 289) objects GroupDeﬁnitions (p. 34)

The groups that are speciﬁed by the Filter or GroupBy parameters in the request.

Type: Array of GroupDeﬁnition (p. 310) objects NextPageToken (p. 34)

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

Pattern: [\S\s]*

ResultsByTime (p. 34)

The time period that's covered by the results in the response.

Type: Array of ResultByTime (p. 336) objects

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

(42)

GetCostAndUsage

HTTP Status Code: 400 RequestChangedException

Your request parameters changed between pages. Try again with the old parameters or without a pagination token.

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>

(43)

GetCostAndUsage

Content-Type: application/x-amz-json-1.1 Content-Length: <PayloadSizeBytes>

Date: <Date>

{

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

} ]

(44)

GetCostAndUsage

}

GetCostAndUsageWithResources

Retrieves cost and usage metrics with resources 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 ﬁlter and group your data by various dimensions, such as SERVICE or AZ, in a speciﬁc 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. This API is currently available for the Amazon Elastic Compute Cloud – Compute service only.

NoteThis is an opt-in only feature. You can enable this feature from the Cost Explorer Settings page.

For information on how to access the Settings page, see Controlling Access for Cost Explorer in the AWS Billing and Cost Management User Guide.

Request Syntax

{

"Filter": { "And": [ "Expression"

],

"Expression"

],

"Tags": {

"Key": "string",

},

"Granularity": "string", "GroupBy": [

{

} ],

"Metrics": [ "string" ], "NextPageToken": "string", "TimePeriod": {

"End": "string", "Start": "string"

}}

Request Parameters

(46)

Filter (p. 39)

Filters Amazon Web Services costs by different dimensions. For example, you can specify SERVICE and LINKED_ACCOUNT and get the costs that are 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 Expression.

The GetCostAndUsageWithResources operation requires that you either group by or ﬁlter by a ResourceId. It requires the Expression "SERVICE = Amazon Elastic Compute Cloud - Compute" in the ﬁlter.

Valid values for MatchOptions for Dimensions are EQUALS and CASE_SENSITIVE.

Valid values for MatchOptions for CostCategories and Tags are EQUALS, ABSENT, and CASE_SENSITIVE. Default values are EQUALS and CASE_SENSITIVE.

Type: Expression (p. 305) object Required: Yes

Granularity (p. 39)

Sets the AWS cost granularity to MONTHLY, DAILY, or HOURLY. If Granularity isn't set, the response object doesn't include the Granularity, MONTHLY, DAILY, or HOURLY.

Type: String

Valid Values: DAILY | MONTHLY | HOURLY Required: Yes

GroupBy (p. 39)

You can group Amazon Web Services costs using up to two diﬀerent groups: DIMENSION, TAG, COST_CATEGORY.

Type: Array of GroupDeﬁnition (p. 310) objects Required: No

Metrics (p. 39)

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, and UsageQuantity.

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

Metrics is required for GetCostAndUsageWithResources requests.

Pattern: [\S\s]*

(47)

Type: String

Pattern: [\S\s]*

Required: No TimePeriod (p. 39)

Sets the start and end dates for retrieving Amazon Web Services costs. The range must be within the last 14 days (the start date cannot be earlier than 14 days ago). 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. 286) object Required: Yes

Response Syntax

{ "DimensionValueAttributes": [ {

"Attributes": { "string" : "string"

},

"Value": "string"

} ],

"NextPageToken": "string", "ResultsByTime": [ {

"Estimated": boolean, "Groups": [

{

"Keys": [ "string" ], "Metrics": {

"string" : {

} } } ],

"TimePeriod": { "End": "string", "Start": "string"

},

(48)

"Total": { "string" : {

} } } ]}

Response Elements

DimensionValueAttributes (p. 41)

The attributes that apply to a speciﬁc dimension value. For example, if the value is a linked account, the attribute is that account name.

Type: Array of DimensionValuesWithAttributes (p. 289) objects GroupDeﬁnitions (p. 41)

The groups that are speciﬁed by the Filter or GroupBy parameters in the request.

Type: Array of GroupDeﬁnition (p. 310) objects NextPageToken (p. 41)

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

Pattern: [\S\s]*

ResultsByTime (p. 41)

The time period that is covered by the results in the response.

Type: Array of ResultByTime (p. 336) objects

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

AWS Billing and Cost Management API Reference