openapi: 3.1.0
info:
  title: AWS Cost Explorer API
  description: >-
    The AWS Cost Explorer API provides programmatic access to AWS cost and
    usage data. Query, filter, group, and aggregate cost data, generate
    forecasts, detect anomalies, and get rightsizing and Savings Plans
    recommendations.
  version: '2017-10-25'
  contact:
    url: https://aws.amazon.com/contact-us/
  termsOfService: https://aws.amazon.com/service-terms/
externalDocs:
  description: AWS Cost Explorer API Reference
  url: https://docs.aws.amazon.com/aws-cost-management/latest/APIReference/
servers:
  - url: https://ce.us-east-1.amazonaws.com
    description: AWS Cost Explorer (Global endpoint via us-east-1)
tags:
  - name: Cost And Usage
    description: Query cost and usage data
  - name: Forecasting
    description: Generate cost and usage forecasts
  - name: Anomaly Detection
    description: Detect and manage cost anomalies
  - name: Recommendations
    description: Cost optimization recommendations
  - name: Tags
    description: Manage cost allocation tags
  - name: Cost Categories
    description: Organize costs with custom categories
  - name: Budgets
    description: Create and manage cost budgets
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, and filter and group your data by various dimensions, such
        as SERVICE or AZ, in a specific time range.
      tags:
        - Cost And Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCostAndUsageRequest'
      responses:
        '200':
          description: Cost and usage data returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCostAndUsageResponse'
        '400':
          $ref: '#/components/responses/DataUnavailableException'
        '500':
          $ref: '#/components/responses/LimitExceededException'
  /GetCostAndUsageWithResources:
    post:
      operationId: GetCostAndUsageWithResources
      summary: Get Cost And Usage With Resources
      description: >-
        Retrieves cost and usage metrics with resources for your account.
        Supports resource-level data for EC2 instances.
      tags:
        - Cost And Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCostAndUsageRequest'
      responses:
        '200':
          description: Cost and usage with resources returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCostAndUsageResponse'
        '400':
          $ref: '#/components/responses/DataUnavailableException'
  /GetCostForecast:
    post:
      operationId: GetCostForecast
      summary: Get Cost Forecast
      description: >-
        Retrieves a forecast for how much Amazon Web Services predicts that you
        will spend over the forecast time period that you select, based on your
        past costs.
      tags:
        - Forecasting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCostForecastRequest'
      responses:
        '200':
          description: Cost forecast returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCostForecastResponse'
        '400':
          $ref: '#/components/responses/DataUnavailableException'
  /GetUsageForecast:
    post:
      operationId: GetUsageForecast
      summary: Get Usage Forecast
      description: >-
        Retrieves a forecast for how much Amazon Web Services predicts that
        you will use over the forecast time period that you select.
      tags:
        - Forecasting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetUsageForecastRequest'
      responses:
        '200':
          description: Usage forecast returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCostForecastResponse'
        '400':
          $ref: '#/components/responses/DataUnavailableException'
  /CreateAnomalyMonitor:
    post:
      operationId: CreateAnomalyMonitor
      summary: Create Anomaly Monitor
      description: >-
        Creates a new cost anomaly detection monitor with the requested type
        and monitor specification.
      tags:
        - Anomaly Detection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnomalyMonitorRequest'
      responses:
        '200':
          description: Anomaly monitor created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAnomalyMonitorResponse'
        '400':
          $ref: '#/components/responses/LimitExceededException'
  /GetAnomalies:
    post:
      operationId: GetAnomalies
      summary: Get Anomalies
      description: >-
        Retrieves all of the cost anomalies detected on your account during
        the time period that's specified in the DateInterval object.
      tags:
        - Anomaly Detection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAnomaliesRequest'
      responses:
        '200':
          description: Anomalies returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAnomaliesResponse'
        '400':
          $ref: '#/components/responses/LimitExceededException'
  /CreateAnomalySubscription:
    post:
      operationId: CreateAnomalySubscription
      summary: Create Anomaly Subscription
      description: >-
        Adds an alert subscription to a cost anomaly detection monitor.
        You can use each subscription to define subscribers with email or SNS
        targets and a frequency for anomaly notifications.
      tags:
        - Anomaly Detection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnomalySubscriptionRequest'
      responses:
        '200':
          description: Anomaly subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAnomalySubscriptionResponse'
        '400':
          $ref: '#/components/responses/LimitExceededException'
  /GetRightsizingRecommendation:
    post:
      operationId: GetRightsizingRecommendation
      summary: Get Rightsizing Recommendation
      description: >-
        Creates recommendations that help you save cost by identifying idle
        and underutilized Amazon EC2 instances.
      tags:
        - Recommendations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRightsizingRecommendationRequest'
      responses:
        '200':
          description: Rightsizing recommendations returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRightsizingRecommendationResponse'
        '400':
          $ref: '#/components/responses/InvalidNextTokenException'
  /GetSavingsPlansPurchaseRecommendation:
    post:
      operationId: GetSavingsPlansPurchaseRecommendation
      summary: Get Savings Plans Purchase Recommendation
      description: >-
        Retrieves the Savings Plans recommendations for your account.
      tags:
        - Recommendations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                SavingsPlansType:
                  type: string
                TermInYears:
                  type: string
                PaymentOption:
                  type: string
                LookbackPeriodInDays:
                  type: string
      responses:
        '200':
          description: Savings Plans recommendations returned
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/LimitExceededException'
  /GetReservationPurchaseRecommendation:
    post:
      operationId: GetReservationPurchaseRecommendation
      summary: Get Reservation Purchase Recommendation
      description: >-
        Gets recommendations for Reserved Instance purchases based on usage
        patterns.
      tags:
        - Recommendations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Service:
                  type: string
                TermInYears:
                  type: string
                PaymentOption:
                  type: string
                LookbackPeriodInDays:
                  type: string
      responses:
        '200':
          description: Reservation purchase recommendations returned
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/LimitExceededException'
  /ListCostAllocationTags:
    post:
      operationId: ListCostAllocationTags
      summary: List Cost Allocation Tags
      description: >-
        Get a list of cost allocation tags. For a list of cost allocation tag
        types, see Tag types in the AWS Billing and Cost Management User Guide.
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Status:
                  type: string
                TagKeys:
                  type: array
                  items:
                    type: string
                MaxResults:
                  type: integer
                NextToken:
                  type: string
      responses:
        '200':
          description: Cost allocation tags returned
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/LimitExceededException'
  /GetTags:
    post:
      operationId: GetTags
      summary: Get Tags
      description: >-
        Queries for available tag keys and tag values for a specified period.
        You can search the tag values via the Filter parameter or that pertain
        to a specific tag key by using the TagKey parameter.
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                TimePeriod:
                  $ref: '#/components/schemas/DateInterval'
                TagKey:
                  type: string
                SearchString:
                  type: string
      responses:
        '200':
          description: Tags returned
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/DataUnavailableException'
  /CreateCostCategoryDefinition:
    post:
      operationId: CreateCostCategoryDefinition
      summary: Create Cost Category Definition
      description: >-
        Creates a new Cost Category with the requested name and rules.
      tags:
        - Cost Categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCostCategoryRequest'
      responses:
        '200':
          description: Cost category created
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/LimitExceededException'
  /ListCostCategoryDefinitions:
    post:
      operationId: ListCostCategoryDefinitions
      summary: List Cost Category Definitions
      description: >-
        Returns the name, ARN, rules, definition, and effective dates of all
        Cost Categories defined in the account.
      tags:
        - Cost Categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                MaxResults:
                  type: integer
                NextToken:
                  type: string
      responses:
        '200':
          description: Cost categories returned
          content:
            application/json:
              schema:
                type: object
        '500':
          $ref: '#/components/responses/LimitExceededException'
  /GetDimensionValues:
    post:
      operationId: GetDimensionValues
      summary: Get Dimension Values
      description: >-
        Retrieves all available filter values for a specified filter over a
        period of time. For example, you can search the EC2 cost category
        entries for a specific month.
      tags:
        - Cost And Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                TimePeriod:
                  $ref: '#/components/schemas/DateInterval'
                Dimension:
                  type: string
                  description: >-
                    The name of the dimension (e.g., SERVICE, REGION, AZ,
                    LINKED_ACCOUNT, USAGE_TYPE, OPERATION)
                SearchString:
                  type: string
                Context:
                  type: string
      responses:
        '200':
          description: Dimension values returned
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/DataUnavailableException'
components:
  schemas:
    DateInterval:
      type: object
      required:
        - Start
        - End
      properties:
        Start:
          type: string
          description: 'Start of the time period in YYYY-MM-DD format'
          example: '2026-01-01'
        End:
          type: string
          description: 'End of the time period in YYYY-MM-DD format'
          example: '2026-04-01'
    Expression:
      type: object
      description: >-
        Filter expression to apply to cost and usage data. Can filter
        by dimensions, tags, or cost categories.
      properties:
        Dimensions:
          type: object
          properties:
            Key:
              type: string
            Values:
              type: array
              items:
                type: string
        Tags:
          type: object
          properties:
            Key:
              type: string
            Values:
              type: array
              items:
                type: string
        And:
          type: array
          items:
            type: object
        Or:
          type: array
          items:
            type: object
        Not:
          type: object
    GroupDefinition:
      type: object
      properties:
        Type:
          type: string
          enum:
            - DIMENSION
            - TAG
            - COST_CATEGORY
        Key:
          type: string
    GetCostAndUsageRequest:
      type: object
      required:
        - TimePeriod
        - Granularity
        - Metrics
      properties:
        TimePeriod:
          $ref: '#/components/schemas/DateInterval'
        Granularity:
          type: string
          enum:
            - DAILY
            - MONTHLY
            - HOURLY
        Filter:
          $ref: '#/components/schemas/Expression'
        Metrics:
          type: array
          items:
            type: string
          description: >-
            Metrics to return. Options: AmortizedCost, BlendedCost,
            NormalizedUsageAmount, UnblendedCost, UsageQuantity,
            NetAmortizedCost, NetUnblendedCost
        GroupBy:
          type: array
          items:
            $ref: '#/components/schemas/GroupDefinition'
        NextPageToken:
          type: string
    GetCostAndUsageResponse:
      type: object
      properties:
        ResultsByTime:
          type: array
          items:
            type: object
            properties:
              TimePeriod:
                $ref: '#/components/schemas/DateInterval'
              Total:
                type: object
              Groups:
                type: array
              Estimated:
                type: boolean
        DimensionValueAttributes:
          type: array
        NextPageToken:
          type: string
    GetCostForecastRequest:
      type: object
      required:
        - TimePeriod
        - Metric
        - Granularity
      properties:
        TimePeriod:
          $ref: '#/components/schemas/DateInterval'
        Metric:
          type: string
          enum:
            - AMORTIZED_COST
            - BLENDED_COST
            - NET_AMORTIZED_COST
            - NET_UNBLENDED_COST
            - UNBLENDED_COST
        Granularity:
          type: string
          enum:
            - DAILY
            - MONTHLY
        Filter:
          $ref: '#/components/schemas/Expression'
        PredictionIntervalLevel:
          type: integer
          minimum: 51
          maximum: 99
    GetCostForecastResponse:
      type: object
      properties:
        Total:
          type: object
          properties:
            Amount:
              type: string
            Unit:
              type: string
        ForecastResultsByTime:
          type: array
          items:
            type: object
    GetUsageForecastRequest:
      type: object
      required:
        - TimePeriod
        - Metric
        - Granularity
      properties:
        TimePeriod:
          $ref: '#/components/schemas/DateInterval'
        Metric:
          type: string
        Granularity:
          type: string
        Filter:
          $ref: '#/components/schemas/Expression'
    CreateAnomalyMonitorRequest:
      type: object
      required:
        - AnomalyMonitor
      properties:
        AnomalyMonitor:
          type: object
          required:
            - MonitorName
            - MonitorType
          properties:
            MonitorName:
              type: string
            MonitorType:
              type: string
              enum:
                - DIMENSIONAL
                - CUSTOM
            MonitorDimension:
              type: string
              enum:
                - SERVICE
            MonitorSpecification:
              $ref: '#/components/schemas/Expression'
        ResourceTags:
          type: array
          items:
            type: object
    CreateAnomalyMonitorResponse:
      type: object
      properties:
        MonitorArn:
          type: string
    GetAnomaliesRequest:
      type: object
      required:
        - DateInterval
      properties:
        MonitorArn:
          type: string
        DateInterval:
          $ref: '#/components/schemas/DateInterval'
        Feedback:
          type: string
          enum:
            - YES
            - NO
            - PLANNED_ACTIVITY
        TotalImpact:
          type: object
        NextPageToken:
          type: string
        MaxResults:
          type: integer
    GetAnomaliesResponse:
      type: object
      properties:
        Anomalies:
          type: array
          items:
            type: object
            properties:
              AnomalyId:
                type: string
              AnomalyStartDate:
                type: string
              AnomalyEndDate:
                type: string
              DimensionValue:
                type: string
              MonitorArn:
                type: string
              AnomalyScore:
                type: object
              Impact:
                type: object
              Feedback:
                type: string
        NextPageToken:
          type: string
    CreateAnomalySubscriptionRequest:
      type: object
      required:
        - AnomalySubscription
      properties:
        AnomalySubscription:
          type: object
          required:
            - MonitorArnList
            - Subscribers
            - Frequency
            - SubscriptionName
          properties:
            MonitorArnList:
              type: array
              items:
                type: string
            Subscribers:
              type: array
              items:
                type: object
                properties:
                  Address:
                    type: string
                  Type:
                    type: string
                    enum:
                      - EMAIL
                      - SNS
            Threshold:
              type: number
            Frequency:
              type: string
              enum:
                - DAILY
                - IMMEDIATE
                - WEEKLY
            SubscriptionName:
              type: string
    CreateAnomalySubscriptionResponse:
      type: object
      properties:
        SubscriptionArn:
          type: string
    GetRightsizingRecommendationRequest:
      type: object
      required:
        - Service
      properties:
        Filter:
          $ref: '#/components/schemas/Expression'
        Configuration:
          type: object
          properties:
            RecommendationTarget:
              type: string
              enum:
                - SAME_INSTANCE_FAMILY
                - CROSS_INSTANCE_FAMILY
            BenefitsConsidered:
              type: boolean
        Service:
          type: string
          description: The specific service that you want recommendations for (e.g., AmazonEC2)
        PageSize:
          type: integer
        NextPageToken:
          type: string
    GetRightsizingRecommendationResponse:
      type: object
      properties:
        Metadata:
          type: object
        Summary:
          type: object
        RightsizingRecommendations:
          type: array
          items:
            type: object
        NextPageToken:
          type: string
    CreateCostCategoryRequest:
      type: object
      required:
        - Name
        - RuleVersion
        - Rules
      properties:
        Name:
          type: string
        EffectiveStart:
          type: string
        RuleVersion:
          type: string
          enum:
            - CostCategoryExpression.v1
        Rules:
          type: array
          items:
            type: object
            properties:
              Value:
                type: string
              Rule:
                $ref: '#/components/schemas/Expression'
              InheritedValue:
                type: object
              Type:
                type: string
        DefaultValue:
          type: string
        SplitChargeRules:
          type: array
          items:
            type: object
    ErrorResponse:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
  responses:
    DataUnavailableException:
      description: The requested data is unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    LimitExceededException:
      description: You've exceeded the limit for this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InvalidNextTokenException:
      description: The pagination token is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    aws_iam:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4 authentication
security:
  - aws_iam: []