AWS API Changes

2026/06/03 - AWS Cost Explorer Service - 3 updated api methods

Changes Added support for target-coverage-based Savings Plans purchase analysis. The StartCommitmentPurchaseAnalysis API now accepts a new TARGET AVERAGE COVERAGE value for AnalysisType, as well as an optional SavingsPlansTargetCoverage field in SavingsPlansPurchaseAnalysisConfiguration

GetCommitmentPurchaseAnalysis (updated)

Link ¶
Changes (response)

{'CommitmentPurchaseAnalysisConfiguration': {'SavingsPlansPurchaseAnalysisConfiguration': {'AnalysisType': {'TARGET_AVERAGE_COVERAGE'},
                                                                                           'SavingsPlansTargetCoverage': 'integer'}}}

Retrieves a commitment purchase analysis result based on the AnalysisId.

See also: AWS API Documentation

Request Syntax

client.get_commitment_purchase_analysis(
    AnalysisId='string'
)

type AnalysisId:

string

param AnalysisId:

[REQUIRED]

The analysis ID that's associated with the commitment purchase analysis.

rtype:

dict

returns:

Response Syntax

{
    'EstimatedCompletionTime': 'string',
    'AnalysisCompletionTime': 'string',
    'AnalysisStartedTime': 'string',
    'AnalysisId': 'string',
    'AnalysisStatus': 'SUCCEEDED'|'PROCESSING'|'FAILED',
    'ErrorCode': 'NO_USAGE_FOUND'|'INTERNAL_FAILURE'|'INVALID_SAVINGS_PLANS_TO_ADD'|'INVALID_SAVINGS_PLANS_TO_EXCLUDE'|'INVALID_ACCOUNT_ID',
    'AnalysisDetails': {
        'SavingsPlansPurchaseAnalysisDetails': {
            'CurrencyCode': 'string',
            'LookbackPeriodInHours': 'string',
            'CurrentAverageCoverage': 'string',
            'CurrentAverageHourlyOnDemandSpend': 'string',
            'CurrentMaximumHourlyOnDemandSpend': 'string',
            'CurrentMinimumHourlyOnDemandSpend': 'string',
            'CurrentOnDemandSpend': 'string',
            'ExistingHourlyCommitment': 'string',
            'HourlyCommitmentToPurchase': 'string',
            'EstimatedAverageCoverage': 'string',
            'EstimatedAverageUtilization': 'string',
            'EstimatedMonthlySavingsAmount': 'string',
            'EstimatedOnDemandCost': 'string',
            'EstimatedOnDemandCostWithCurrentCommitment': 'string',
            'EstimatedROI': 'string',
            'EstimatedSavingsAmount': 'string',
            'EstimatedSavingsPercentage': 'string',
            'EstimatedCommitmentCost': 'string',
            'LatestUsageTimestamp': 'string',
            'UpfrontCost': 'string',
            'AdditionalMetadata': 'string',
            'MetricsOverLookbackPeriod': [
                {
                    'StartTime': 'string',
                    'EstimatedOnDemandCost': 'string',
                    'CurrentCoverage': 'string',
                    'EstimatedCoverage': 'string',
                    'EstimatedNewCommitmentUtilization': 'string'
                },
            ]
        }
    },
    'CommitmentPurchaseAnalysisConfiguration': {
        'SavingsPlansPurchaseAnalysisConfiguration': {
            'AccountScope': 'PAYER'|'LINKED',
            'AccountId': 'string',
            'AnalysisType': 'MAX_SAVINGS'|'CUSTOM_COMMITMENT'|'TARGET_AVERAGE_COVERAGE',
            'SavingsPlansToAdd': [
                {
                    'PaymentOption': 'NO_UPFRONT'|'PARTIAL_UPFRONT'|'ALL_UPFRONT'|'LIGHT_UTILIZATION'|'MEDIUM_UTILIZATION'|'HEAVY_UTILIZATION',
                    'SavingsPlansType': 'COMPUTE_SP'|'EC2_INSTANCE_SP'|'SAGEMAKER_SP'|'DATABASE_SP',
                    'Region': 'string',
                    'InstanceFamily': 'string',
                    'TermInYears': 'ONE_YEAR'|'THREE_YEARS',
                    'SavingsPlansCommitment': 123.0,
                    'OfferingId': 'string'
                },
            ],
            'SavingsPlansToExclude': [
                'string',
            ],
            'LookBackTimePeriod': {
                'Start': 'string',
                'End': 'string'
            },
            'SavingsPlansTargetCoverage': 123
        }
    }
}

Response Structure

(dict) --
- EstimatedCompletionTime (string) --
  
  The estimated time for when the analysis will complete.
- AnalysisCompletionTime (string) --
  
  The completion time of the analysis.
- AnalysisStartedTime (string) --
  
  The start time of the analysis.
- AnalysisId (string) --
  
  The analysis ID that's associated with the commitment purchase analysis.
- AnalysisStatus (string) --
  
  The status of the analysis.
- ErrorCode (string) --
  
  The error code used for the analysis.
- AnalysisDetails (dict) --
  
  Details about the analysis.
  - SavingsPlansPurchaseAnalysisDetails (dict) --
    
    Details about the Savings Plans purchase analysis.
    - CurrencyCode (string) --
      
      The currency code used for the analysis.
    - LookbackPeriodInHours (string) --
      
      The lookback period in hours that's used to generate the analysis.
    - CurrentAverageCoverage (string) --
      
      The average value of hourly coverage over the lookback period.
    - CurrentAverageHourlyOnDemandSpend (string) --
      
      The average value of hourly On-Demand spend over the lookback period.
    - CurrentMaximumHourlyOnDemandSpend (string) --
      
      The highest value of hourly On-Demand spend over the lookback period.
    - CurrentMinimumHourlyOnDemandSpend (string) --
      
      The lowest value of hourly On-Demand spend over the lookback period.
    - CurrentOnDemandSpend (string) --
      
      The current total On-Demand spend over the lookback period.
    - ExistingHourlyCommitment (string) --
      
      The existing hourly commitment for the Savings Plan type.
    - HourlyCommitmentToPurchase (string) --
      
      The recommended or custom hourly commitment.
    - EstimatedAverageCoverage (string) --
      
      The estimated coverage of the Savings Plan.
    - EstimatedAverageUtilization (string) --
      
      The estimated utilization of the Savings Plan.
    - EstimatedMonthlySavingsAmount (string) --
      
      The estimated monthly savings amount based on the Savings Plan.
    - EstimatedOnDemandCost (string) --
      
      The remaining On-Demand cost estimated to not be covered by the Savings Plan over the length of the lookback period.
    - EstimatedOnDemandCostWithCurrentCommitment (string) --
      
      The estimated On-Demand cost you expect with no additional commitment based on your usage of the selected time period and the Savings Plan you own.
    - EstimatedROI (string) --
      
      The estimated return on investment that's based on the Savings Plan and estimated savings. This is calculated as estimatedSavingsAmount/estimatedSPCost*100.
    - EstimatedSavingsAmount (string) --
      
      The estimated savings amount that's based on the Savings Plan over the length of the lookback period.
    - EstimatedSavingsPercentage (string) --
      
      The estimated savings percentage relative to the total cost over the cost calculation lookback period.
    - EstimatedCommitmentCost (string) --
      
      The estimated cost of the Savings Plan over the length of the lookback period.
    - LatestUsageTimestamp (string) --
      
      The date and time of the last hour that went into the analysis.
    - UpfrontCost (string) --
      
      The upfront cost of the Savings Plan based on the selected payment option.
    - AdditionalMetadata (string) --
      
      Additional metadata that might be applicable to the commitment.
    - MetricsOverLookbackPeriod (list) --
      
      The related hourly cost, coverage, and utilization metrics over the lookback period.
      - (dict) --
        
        Contains the hourly metrics for the given recommendation over the lookback period.
        
        StartTime (string) --
        
        The period of time that you want the usage and costs for.
        
        EstimatedOnDemandCost (string) --
        
        The remaining On-Demand cost estimated to not be covered by the recommended Savings Plan, over the length of the lookback period.
        
        CurrentCoverage (string) --
        
        The current amount of Savings Plans eligible usage that the Savings Plan covered.
        
        EstimatedCoverage (string) --
        
        The estimated coverage amount based on the recommended Savings Plan.
        
        EstimatedNewCommitmentUtilization (string) --
        
        The estimated utilization for the recommended Savings Plan.
- CommitmentPurchaseAnalysisConfiguration (dict) --
  
  The configuration for the commitment purchase analysis.
  - SavingsPlansPurchaseAnalysisConfiguration (dict) --
    
    The configuration for the Savings Plans purchase analysis.
    - AccountScope (string) --
      
      The account scope that you want your analysis for.
    - AccountId (string) --
      
      The account that the analysis is for.
    - AnalysisType (string) --
      
      The type of analysis.
    - SavingsPlansToAdd (list) --
      
      Savings Plans to include in the analysis.
      - (dict) --
        
        The Savings Plans commitment details.
        
        PaymentOption (string) --
        
        The payment option for the Savings Plans commitment.
        
        SavingsPlansType (string) --
        
        The Savings Plans type.
        
        Region (string) --
        
        The Region associated with the Savings Plans commitment.
        
        InstanceFamily (string) --
        
        The instance family of the Savings Plans commitment.
        
        TermInYears (string) --
        
        The term that you want the Savings Plans commitment for.
        
        SavingsPlansCommitment (float) --
        
        The Savings Plans commitment.
        
        OfferingId (string) --
        
        The unique ID that's used to distinguish Savings Plans commitments from one another.
    - SavingsPlansToExclude (list) --
      
      Savings Plans to exclude from the analysis.
      - (string) --
    - LookBackTimePeriod (dict) --
      
      The time period associated with the analysis.
      - Start (string) --
        
        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 (string) --
        
        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.
    - SavingsPlansTargetCoverage (integer) --
      
      Specifies the target Savings Plans coverage as a percentage from 10 to 100. This field is required when AnalysisType is TARGET_AVERAGE_COVERAGE. It defines the target average hourly coverage that the recommended Savings Plans commitment should achieve over the lookback period.

ListCommitmentPurchaseAnalyses (updated)

Link ¶
Changes (response)

{'AnalysisSummaryList': {'CommitmentPurchaseAnalysisConfiguration': {'SavingsPlansPurchaseAnalysisConfiguration': {'AnalysisType': {'TARGET_AVERAGE_COVERAGE'},
                                                                                                                   'SavingsPlansTargetCoverage': 'integer'}}}}

Lists the commitment purchase analyses for your account.

See also: AWS API Documentation

Request Syntax

client.list_commitment_purchase_analyses(
    AnalysisStatus='SUCCEEDED'|'PROCESSING'|'FAILED',
    NextPageToken='string',
    PageSize=123,
    AnalysisIds=[
        'string',
    ]
)

type AnalysisStatus:

string

param AnalysisStatus:

The status of the analysis.

type NextPageToken:

string

param NextPageToken:

The token to retrieve the next set of results.

type PageSize:

integer

param PageSize:

The number of analyses that you want returned in a single response object.

type AnalysisIds:

list

param AnalysisIds:

The analysis IDs associated with the commitment purchase analyses.

(string) --

rtype:

dict

returns:

Response Syntax

{
    'AnalysisSummaryList': [
        {
            'EstimatedCompletionTime': 'string',
            'AnalysisCompletionTime': 'string',
            'AnalysisStartedTime': 'string',
            'AnalysisStatus': 'SUCCEEDED'|'PROCESSING'|'FAILED',
            'ErrorCode': 'NO_USAGE_FOUND'|'INTERNAL_FAILURE'|'INVALID_SAVINGS_PLANS_TO_ADD'|'INVALID_SAVINGS_PLANS_TO_EXCLUDE'|'INVALID_ACCOUNT_ID',
            'AnalysisId': 'string',
            'CommitmentPurchaseAnalysisConfiguration': {
                'SavingsPlansPurchaseAnalysisConfiguration': {
                    'AccountScope': 'PAYER'|'LINKED',
                    'AccountId': 'string',
                    'AnalysisType': 'MAX_SAVINGS'|'CUSTOM_COMMITMENT'|'TARGET_AVERAGE_COVERAGE',
                    'SavingsPlansToAdd': [
                        {
                            'PaymentOption': 'NO_UPFRONT'|'PARTIAL_UPFRONT'|'ALL_UPFRONT'|'LIGHT_UTILIZATION'|'MEDIUM_UTILIZATION'|'HEAVY_UTILIZATION',
                            'SavingsPlansType': 'COMPUTE_SP'|'EC2_INSTANCE_SP'|'SAGEMAKER_SP'|'DATABASE_SP',
                            'Region': 'string',
                            'InstanceFamily': 'string',
                            'TermInYears': 'ONE_YEAR'|'THREE_YEARS',
                            'SavingsPlansCommitment': 123.0,
                            'OfferingId': 'string'
                        },
                    ],
                    'SavingsPlansToExclude': [
                        'string',
                    ],
                    'LookBackTimePeriod': {
                        'Start': 'string',
                        'End': 'string'
                    },
                    'SavingsPlansTargetCoverage': 123
                }
            }
        },
    ],
    'NextPageToken': 'string'
}

Response Structure

(dict) --
- AnalysisSummaryList (list) --
  
  The list of analyses.
  - (dict) --
    
    A summary of the analysis.
    - EstimatedCompletionTime (string) --
      
      The estimated time for when the analysis will complete.
    - AnalysisCompletionTime (string) --
      
      The completion time of the analysis.
    - AnalysisStartedTime (string) --
      
      The start time of the analysis.
    - AnalysisStatus (string) --
      
      The status of the analysis.
    - ErrorCode (string) --
      
      The error code used for the analysis.
    - AnalysisId (string) --
      
      The analysis ID that's associated with the commitment purchase analysis.
    - CommitmentPurchaseAnalysisConfiguration (dict) --
      
      The configuration for the commitment purchase analysis.
      - SavingsPlansPurchaseAnalysisConfiguration (dict) --
        
        The configuration for the Savings Plans purchase analysis.
        
        AccountScope (string) --
        
        The account scope that you want your analysis for.
        
        AccountId (string) --
        
        The account that the analysis is for.
        
        AnalysisType (string) --
        
        The type of analysis.
        
        SavingsPlansToAdd (list) --
        
        Savings Plans to include in the analysis.
        
        (dict) --
        
        The Savings Plans commitment details.
        
        PaymentOption (string) --
        
        The payment option for the Savings Plans commitment.
        
        SavingsPlansType (string) --
        
        The Savings Plans type.
        
        Region (string) --
        
        The Region associated with the Savings Plans commitment.
        
        InstanceFamily (string) --
        
        The instance family of the Savings Plans commitment.
        
        TermInYears (string) --
        
        The term that you want the Savings Plans commitment for.
        
        SavingsPlansCommitment (float) --
        
        The Savings Plans commitment.
        
        OfferingId (string) --
        
        The unique ID that's used to distinguish Savings Plans commitments from one another.
        
        SavingsPlansToExclude (list) --
        
        Savings Plans to exclude from the analysis.
        
        (string) --
        
        LookBackTimePeriod (dict) --
        
        The time period associated with the analysis.
        
        Start (string) --
        
        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 (string) --
        
        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.
        
        SavingsPlansTargetCoverage (integer) --
        
        Specifies the target Savings Plans coverage as a percentage from 10 to 100. This field is required when AnalysisType is TARGET_AVERAGE_COVERAGE. It defines the target average hourly coverage that the recommended Savings Plans commitment should achieve over the lookback period.
- NextPageToken (string) --
  
  The token to retrieve the next set of results.

StartCommitmentPurchaseAnalysis (updated)

Link ¶
Changes (request)

{'CommitmentPurchaseAnalysisConfiguration': {'SavingsPlansPurchaseAnalysisConfiguration': {'AnalysisType': {'TARGET_AVERAGE_COVERAGE'},
                                                                                           'SavingsPlansTargetCoverage': 'integer'}}}

Specifies the parameters of a planned commitment purchase and starts the generation of the analysis. This enables you to estimate the cost, coverage, and utilization impact of your planned commitment purchases.