Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: AWS Cost Explorer Service Cost And Usage API
version: '2017-10-25'
description: Generated from AWS's published Smithy model for AWS Cost Explorer Service. 3 operation(s).
contact:
name: Amazon Web Services
url: https://aws.amazon.com/contact-us/
license:
name: Apache 2.0
identifier: Apache-2.0
url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://ce.{region}.amazonaws.com
variables:
region:
default: us-east-1
security:
- sigv4: []
paths:
/#GetCostAndUsage:
post:
operationId: GetCostAndUsage
summary: Get Cost And Usage
description: 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 Organizations have
access to all member accounts. For information about filter limitations, see Quotas and restrictions in the Billing
and Cost Management User Guide.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/GetCostAndUsageResponse'
'400':
description: BillExpirationException; BillingViewHealthStatusException; DataUnavailableException; InvalidNextTokenException;
LimitExceededException; RequestChangedException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/BillExpirationException'
'404':
description: ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ResourceNotFoundException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- AWSInsightsIndexService.GetCostAndUsage
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/GetCostAndUsageRequest'
tags:
- Cost And Usage
/#GetCostAndUsageWithResources:
post:
operationId: GetCostAndUsageWithResources
summary: Get Cost And Usage With Resources
description: 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 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 Organizations have access to all member
accounts. Hourly granularity is only available for EC2-Instances (Elastic Compute Cloud) resource-level data. All
other resource-level data is available at daily granularity. This is an opt-in only feature. You can enable this feature
from the Cost Explorer Settings page. For information about how to access the Settings page, see Controlling Access
for Cost Explorer in the Billing and Cost Management User Guide.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/GetCostAndUsageWithResourcesResponse'
'400':
description: BillExpirationException; BillingViewHealthStatusException; DataUnavailableException; InvalidNextTokenException;
LimitExceededException; RequestChangedException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/BillExpirationException'
'404':
description: ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ResourceNotFoundException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- AWSInsightsIndexService.GetCostAndUsageWithResources
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/GetCostAndUsageWithResourcesRequest'
tags:
- Cost And Usage
/#GetDimensionValues:
post:
operationId: GetDimensionValues
summary: Get Dimension Values
description: Retrieves all available filter values for a specified filter over a period of time. You can search the
dimension values for an arbitrary string.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/GetDimensionValuesResponse'
'400':
description: BillExpirationException; BillingViewHealthStatusException; DataUnavailableException; InvalidNextTokenException;
LimitExceededException; RequestChangedException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/BillExpirationException'
'404':
description: ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ResourceNotFoundException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- AWSInsightsIndexService.GetDimensionValues
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/GetDimensionValuesRequest'
tags:
- Cost And Usage
components:
securitySchemes:
sigv4:
type: apiKey
in: header
name: Authorization
description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
x-aws-sigv4:
signingName: ce
schemas:
BillExpirationException:
type: object
properties:
Message:
type: string
CostCategoryValues:
type: object
properties:
Key:
type: string
Values:
type: array
items:
type: string
description: The specific value of the cost category.
MatchOptions:
type: array
items:
type: string
enum:
- EQUALS
- ABSENT
- STARTS_WITH
- ENDS_WITH
- CONTAINS
- CASE_SENSITIVE
- CASE_INSENSITIVE
- GREATER_THAN_OR_EQUAL
description: The match options that you can use to filter your results. MatchOptions is only applicable for actions
related to cost category. The default values for MatchOptions is EQUALS and CASE_SENSITIVE.
DateInterval:
type: object
properties:
Start:
type: string
description: The beginning of the time period. The start date is inclusive. For example, if start is 2017-01-01,
Amazon Web Services retrieves cost and usage data starting at 2017-01-01 up to the end date. The start date must
be equal to or no later than the current date to avoid a validation error.
End:
type: string
description: The end of the time period. The end date is exclusive. For example, if end is 2017-05-01, Amazon Web
Services retrieves cost and usage data from the start date up to, but not including, 2017-05-01.
required:
- Start
- End
DimensionValues:
type: object
properties:
Key:
type: string
enum:
- AZ
- INSTANCE_TYPE
- LINKED_ACCOUNT
- PAYER_ACCOUNT
- LINKED_ACCOUNT_NAME
- OPERATION
- PURCHASE_TYPE
- REGION
- SERVICE
- SERVICE_CODE
- USAGE_TYPE
- USAGE_TYPE_GROUP
- RECORD_TYPE
- OPERATING_SYSTEM
- TENANCY
- SCOPE
- PLATFORM
- SUBSCRIPTION_ID
- LEGAL_ENTITY_NAME
- DEPLOYMENT_OPTION
- DATABASE_ENGINE
- CACHE_ENGINE
- INSTANCE_TYPE_FAMILY
- BILLING_ENTITY
- RESERVATION_ID
- RESOURCE_ID
- RIGHTSIZING_TYPE
- SAVINGS_PLANS_TYPE
- SAVINGS_PLAN_ARN
- PAYMENT_OPTION
- AGREEMENT_END_DATE_TIME_AFTER
- AGREEMENT_END_DATE_TIME_BEFORE
- INVOICING_ENTITY
- ANOMALY_TOTAL_IMPACT_ABSOLUTE
- ANOMALY_TOTAL_IMPACT_PERCENTAGE
- PRODUCT_ATTRIBUTE
description: 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. Not all dimensions are supported in each API. Refer to the documentation
for each specific API to see what is supported. LINKED_ACCOUNT_NAME and SERVICE_CODE can only be used in CostCategoryRule.
ANOMALY_TOTAL_IMPACT_ABSOLUTE and ANOMALY_TOTAL_IMPACT_PERCENTAGE can only be used in AnomalySubscriptions. Use
PRODUCT_ATTRIBUTE only as the Dimension in GetDimensionValues. To filter or group by product attributes, use the
ProductAttributes field of Expression or t
Values:
type: array
items:
type: string
description: The metadata values that you can use to filter and group your results. You can use GetDimensionValues
to find specific values.
MatchOptions:
type: array
items:
type: string
enum:
- EQUALS
- ABSENT
- STARTS_WITH
- ENDS_WITH
- CONTAINS
- CASE_SENSITIVE
- CASE_INSENSITIVE
- GREATER_THAN_OR_EQUAL
description: The match options that you can use to filter your results. MatchOptions is only applicable for actions
related to cost category and Anomaly Subscriptions. Refer to the documentation for each specific API to see what
is supported. The default values for MatchOptions are EQUALS and CASE_SENSITIVE.
DimensionValuesWithAttributes:
type: object
properties:
Value:
type: string
description: The value of a dimension with a specific attribute.
Attributes:
type: object
additionalProperties:
type: string
description: The attribute that applies to a specific Dimension.
Expression:
type: object
properties:
Or:
type: array
items:
$ref: '#/components/schemas/Expression'
description: Return results that match either Dimension object.
And:
type: array
items:
$ref: '#/components/schemas/Expression'
description: Return results that match both Dimension objects.
Not:
$ref: '#/components/schemas/Expression'
Dimensions:
$ref: '#/components/schemas/DimensionValues'
Tags:
$ref: '#/components/schemas/TagValues'
CostCategories:
$ref: '#/components/schemas/CostCategoryValues'
ProductAttributes:
$ref: '#/components/schemas/ProductAttributeValues'
GetCostAndUsageRequest:
type: object
properties:
TimePeriod:
$ref: '#/components/schemas/DateInterval'
Granularity:
type: string
enum:
- DAILY
- MONTHLY
- HOURLY
description: Sets the Amazon Web Services 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.
Filter:
$ref: '#/components/schemas/Expression'
Metrics:
type: array
items:
type: string
description: 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. 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 d
GroupBy:
type: array
items:
$ref: '#/components/schemas/GroupDefinition'
description: You can group Amazon Web Services costs using up to two different groups, either dimensions, tag keys,
cost categories, product attributes, 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. To group by the PRODUCT_ATTRIBUTE type, set Key to a product attribute key, such as model. For
the keys of each supported service
BillingViewArn:
type: string
description: The Amazon Resource Name (ARN) that uniquely identifies a specific billing view. The ARN is used to
specify which particular billing view you want to interact with or retrieve information from when making API calls
related to Amazon Web Services Billing and Cost Management features. The BillingViewArn can be retrieved by calling
the ListBillingViews API.
NextPageToken:
type: string
description: The token to retrieve the next set of results. Amazon Web Services provides the token when the response
from a previous call has more results than the maximum page size.
required:
- TimePeriod
- Granularity
- Metrics
GetCostAndUsageResponse:
type: object
properties:
NextPageToken:
type: string
description: The token for the next set of retrievable results. Amazon Web Services provides the token when the
response from a previous call has more results than the maximum page size.
GroupDefinitions:
type: array
items:
$ref: '#/components/schemas/GroupDefinition'
description: The groups that are specified by the Filter or GroupBy parameters in the request.
ResultsByTime:
type: array
items:
$ref: '#/components/schemas/ResultByTime'
description: The time period that's covered by the results in the response.
DimensionValueAttributes:
type: array
items:
$ref: '#/components/schemas/DimensionValuesWithAttributes'
description: The attributes that apply to a specific dimension value. For example, if the value is a linked account,
the attribute is that account name.
GetCostAndUsageWithResourcesRequest:
type: object
properties:
TimePeriod:
$ref: '#/components/schemas/DateInterval'
Granularity:
type: string
enum:
- DAILY
- MONTHLY
- HOURLY
description: Sets the Amazon Web Services cost granularity to MONTHLY, DAILY, or HOURLY. If Granularity isn't set,
the response object doesn't include the Granularity, MONTHLY, DAILY, or HOURLY.
Filter:
$ref: '#/components/schemas/Expression'
Metrics:
type: array
items:
type: string
description: 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. If 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 d
GroupBy:
type: array
items:
$ref: '#/components/schemas/GroupDefinition'
description: 'You can group Amazon Web Services costs using up to two different groups: DIMENSION, TAG, COST_CATEGORY,
and PRODUCT_ATTRIBUTE. PRODUCT_ATTRIBUTE groups work the same way as in GetCostAndUsage. A PRODUCT_ATTRIBUTE group
or a ProductAttributes filter doesn''t meet the requirement to group by or filter by a ResourceId.'
BillingViewArn:
type: string
description: The Amazon Resource Name (ARN) that uniquely identifies a specific billing view. The ARN is used to
specify which particular billing view you want to interact with or retrieve information from when making API calls
related to Amazon Web Services Billing and Cost Management features. The BillingViewArn can be retrieved by calling
the ListBillingViews API.
NextPageToken:
type: string
description: The token to retrieve the next set of results. Amazon Web Services provides the token when the response
from a previous call has more results than the maximum page size.
required:
- TimePeriod
- Granularity
- Filter
GetCostAndUsageWithResourcesResponse:
type: object
properties:
NextPageToken:
type: string
description: The token for the next set of retrievable results. Amazon Web Services provides the token when the
response from a previous call has more results than the maximum page size.
GroupDefinitions:
type: array
items:
$ref: '#/components/schemas/GroupDefinition'
description: The groups that are specified by the Filter or GroupBy parameters in the request.
ResultsByTime:
type: array
items:
$ref: '#/components/schemas/ResultByTime'
description: The time period that's covered by the results in the response.
DimensionValueAttributes:
type: array
items:
$ref: '#/components/schemas/DimensionValuesWithAttributes'
description: The attributes that apply to a specific dimension value. For example, if the value is a linked account,
the attribute is that account name.
GetDimensionValuesRequest:
type: object
properties:
SearchString:
type: string
description: The value that you want to search the filter values for.
TimePeriod:
$ref: '#/components/schemas/DateInterval'
Dimension:
type: string
enum:
- AZ
- INSTANCE_TYPE
- LINKED_ACCOUNT
- PAYER_ACCOUNT
- LINKED_ACCOUNT_NAME
- OPERATION
- PURCHASE_TYPE
- REGION
- SERVICE
- SERVICE_CODE
- USAGE_TYPE
- USAGE_TYPE_GROUP
- RECORD_TYPE
- OPERATING_SYSTEM
- TENANCY
- SCOPE
- PLATFORM
- SUBSCRIPTION_ID
- LEGAL_ENTITY_NAME
- DEPLOYMENT_OPTION
- DATABASE_ENGINE
- CACHE_ENGINE
- INSTANCE_TYPE_FAMILY
- BILLING_ENTITY
- RESERVATION_ID
- RESOURCE_ID
- RIGHTSIZING_TYPE
- SAVINGS_PLANS_TYPE
- SAVINGS_PLAN_ARN
- PAYMENT_OPTION
- AGREEMENT_END_DATE_TIME_AFTER
- AGREEMENT_END_DATE_TIME_BEFORE
- INVOICING_ENTITY
- ANOMALY_TOTAL_IMPACT_ABSOLUTE
- ANOMALY_TOTAL_IMPACT_PERCENTAGE
- PRODUCT_ATTRIBUTE
description: The name of the dimension. Each Dimension is available for a different Context. For more information,
see Context. LINK_ACCOUNT_NAME and SERVICE_CODE can only be used in CostCategoryRule. PRODUCT_ATTRIBUTE returns
the product attribute keys that are available for your costs of supported services, or the values of the key that
you specify in DimensionKey. PRODUCT_ATTRIBUTE is supported only in the COST_AND_USAGE context.
DimensionKey:
type: string
description: The product attribute key to return values for, such as model. If you omit DimensionKey or set it to
an empty string, the response lists the product attribute keys that are available for your costs of supported
services instead. For the supported services, see ProductAttributeValues. If you specify a key, the response lists
the values of that key. If some of your costs have no value for the key, the response includes an empty-string
value. Keys are case-sensitive, and a key that doesn't exist returns no values other than an empty string. You
can specify DimensionKey only when Dimension is PROD
Context:
type: string
enum:
- COST_AND_USAGE
- RESERVATIONS
- SAVINGS_PLANS
description: '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 operation. 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 COST_AND_USAGE, you can use the following
dimensions for searching: AZ - The Availability Zone. An example is us-east-1a. BILLING_ENTITY - The Amazon Web
Services seller that your account is with. Poss'
Filter:
$ref: '#/components/schemas/Expression'
SortBy:
type: array
items:
$ref: '#/components/schemas/SortDefinition'
description: 'The value that you want to sort the data by. The key represents cost and usage metrics. The following
values are supported: BlendedCost UnblendedCost AmortizedCost NetAmortizedCost NetUnblendedCost UsageQuantity
NormalizedUsageAmount The supported values for the SortOrder key are ASCENDING or DESCENDING. When you specify
a SortBy paramater, the context must be COST_AND_USAGE. Further, when using SortBy, NextPageToken and SearchString
aren''t supported.'
BillingViewArn:
type: string
description: The Amazon Resource Name (ARN) that uniquely identifies a specific billing view. The ARN is used to
specify which particular billing view you want to interact with or retrieve information from when making API calls
related to Amazon Web Services Billing and Cost Management features. The BillingViewArn can be retrieved by calling
the ListBillingViews API.
MaxResults:
type: integer
description: This field is only used when SortBy is provided in the request. The maximum number of objects that
are returned for this request. If MaxResults isn't specified with SortBy, the request returns 1000 results as
the default value for this parameter. For GetDimensionValues, MaxResults has an upper limit of 1000.
NextPageToken:
type: string
description: The token to retrieve the next set of results. Amazon Web Services provides the token when the response
from a previous call has more results than the maximum page size.
required:
- TimePeriod
- Dimension
GetDimensionValuesResponse:
type: object
properties:
DimensionValues:
type: array
items:
$ref: '#/components/schemas/DimensionValuesWithAttributes'
description: 'The filters that you used to filter your request. Some dimensions are available only for a specific
context. If you set the context to COST_AND_USAGE, you can use the following dimensions for searching: AZ - The
Availability Zone. An example is us-east-1a. DATABASE_ENGINE - The Amazon Relational Database Service database.
Examples are Aurora or MySQL. INSTANCE_TYPE - The type of Amazon EC2 instance. An example is m4.xlarge. LEGAL_ENTITY_NAME
- The name of the organization that sells you Amazon Web Services services, such as Amazon Web Services. LINKED_ACCOUNT
- The description in the attribute'
ReturnSize:
type: integer
description: The number of results that Amazon Web Services returned at one time.
TotalSize:
type: integer
description: The total number of search results.
NextPageToken:
type: string
description: The token for the next set of retrievable results. Amazon Web Services provides the token when the
response from a previous call has more results than the maximum page size.
required:
- DimensionValues
- ReturnSize
- TotalSize
Group:
type: object
properties:
Keys:
type: array
items:
type: string
description: The keys that are included in this group.
Metrics:
type: object
additionalProperties:
$ref: '#/components/schemas/MetricValue'
description: The metrics that are included in this group.
GroupDefinition:
type: object
properties:
Type:
type: string
enum:
- DIMENSION
- TAG
- COST_CATEGORY
- PRODUCT_ATTRIBUTE
description: The string that represents the type of group.
Key:
type: string
description: The string that represents a key for a specified group.
MetricValue:
type: object
properties:
Amount:
type: string
description: The actual number that represents the metric.
Unit:
type: string
description: The unit that the metric is given in.
ProductAttributeValues:
type: object
properties:
Key:
type: string
description: 'The name of the product attribute, such as model. The keys that are available depend on the service.
For the keys of each supported service, see ProductAttributeValues . Keys are case-sensitive. A key that doesn''t
exist doesn''t return an error: EQUALS matches no costs, and ABSENT matches all costs of supported services.'
Values:
type: array
items:
type: string
description: The specific values of the product attribute, such as Claude Sonnet 5 for the model key. Values are
matched exactly, including case. To list the values of a key, use GetDimensionValues with Dimension set to PRODUCT_ATTRIBUTE
and DimensionKey set to the key. To match costs that have no value for the key, set MatchOptions to ABSENT and
omit Values. Otherwise, Values is required.
MatchOptions:
type: array
items:
type: string
enum:
- EQUALS
- ABSENT
- STARTS_WITH
- ENDS_WITH
- CONTAINS
- CASE_SENSITIVE
- CASE_INSENSITIVE
- GREATER_THAN_OR_EQUAL
description: 'The match options that you can use to filter your results. Valid values: EQUALS - Matches the values
that you specify. ABSENT - Matches costs that have no value for the key. Omit Values. CASE_SENSITIVE - Use only
with EQUALS. Values are always matched case-sensitively. Default values are EQUALS and CASE_SENSITIVE.'
required:
- Key
ResourceNotFoundException:
type: object
properties:
Message:
type: string
ResourceName:
type: string
ResultByTime:
type: object
properties:
TimePeriod:
$ref: '#/components/schemas/DateInterval'
Total:
type: object
additionalProperties:
$ref: '#/components/schemas/MetricValue'
description: The total amount of cost or usage accrued during the time period.
Groups:
type: array
items:
$ref: '#/components/schemas/Group'
description: The groups that this time period includes.
Estimated:
type: boolean
description: Determines whether the result is estimated.
SortDefinition:
type: object
properties:
Key:
type: string
description: The key that's used to sort the data.
SortOrder:
type: string
enum:
- ASCENDING
- DESCENDING
description: The order that's used to sort the data.
required:
- Key
TagValues:
type: object
properties:
Key:
type: string
description: The key for the tag.
Values:
type: array
items:
type: string
description: The specific value of the tag.
MatchOptions:
type: array
items:
type: string
enum:
- EQUALS
- ABSENT
- STARTS_WITH
- ENDS_WITH
- CONTAINS
- CASE_SENSITIVE
- CASE_INSENSITIVE
- GREATER_THAN_OR_EQUAL
description: The match options that you can use to filter your results. MatchOptions is only applicable for actions
related to cost category. The default values for MatchOptions are EQUALS and CASE_SENSITIVE.
x-provenance:
method: harvested
publisher: Amazon Web Services
source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/cost-explorer/service/2017-10-25/cost-explorer-2017-10-25.json
note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)