Boto3 get_savings_plans_utilization_details DIMENSION as INSTANCE_TYPE?

Hi tranquilv,

You're correct — this is a known documentation discrepancy. The boto3/AWS SDK docs list INSTANCE_TYPE as a valid dimension in the generic Expression object shared across many Cost Explorer APIs, but GetSavingsPlansUtilizationDetails only supports a subset of dimensions for filtering.

Confirmed Supported Dimensions

Per the AWS SDK for Ruby V3 docs (which are more precise than the boto3 auto-generated docs), GetSavingsPlansUtilizationDetails supports only these filter dimensions:

• LINKED_ACCOUNT
• SAVINGS_PLAN_ARN
• INSTANCE_TYPE_FAMILY

The error message you received confirms this. The INSTANCE_TYPE (e.g., m6g.medium) granularity is not available through this API.

Why the Documentation Is Misleading

The Cost Explorer APIs share a common Expression object definition that includes ALL possible dimension keys (INSTANCE_TYPE, SERVICE, REGION, etc.). However, each specific API endpoint only accepts a subset. The auto-generated SDK documentation (including boto3) shows the full Expression schema without clearly indicating which dimensions each individual API actually supports. You can discover the actual allowed dimensions at runtime using:

response = ce.get_dimension_values(
    TimePeriod={'Start': '2024-05-01', 'End': '2024-05-17'},
    Dimension='SAVINGS_PLANS_TYPE',  # or other valid dimensions
    Context='SAVINGS_PLANS'
)

Workaround: Getting SP Utilization by Instance Type

Since the Savings Plans APIs don't support INSTANCE_TYPE granularity, here are alternatives:

Option 1: AWS Cost and Usage Report (CUR)

CUR gives you the most granular data. Enable the AWS Cost and Usage Report, then query with Athena:

SELECT 
    line_item_usage_type,
    product_instance_type,
    savings_plan_savings_plan_a_r_n,
    SUM(savings_plan_savings_plan_effective_cost) AS sp_effective_cost,
    SUM(savings_plan_total_commitment_to_date) AS commitment,
    SUM(savings_plan_used_commitment) AS used_commitment
FROM cur_database.cur_table
WHERE savings_plan_savings_plan_a_r_n != ''
    AND line_item_line_item_type = 'SavingsPlanCoveredUsage'
    AND billing_period = '2024-05'
GROUP BY 1, 2, 3
ORDER BY sp_effective_cost DESC;

This gives you per-instance-type breakdown of Savings Plans utilization.

Option 2: GetCostAndUsage API with GroupBy

Use GetCostAndUsage instead, which supports INSTANCE_TYPE as a group-by dimension:

response = ce.get_cost_and_usage(
    TimePeriod={'Start': '2024-05-01', 'End': '2024-05-17'},
    Granularity='DAILY',
    Filter={
        'Dimensions': {
            'Key': 'RECORD_TYPE',
            'Values': ['SavingsPlanCoveredUsage']
        }
    },
    GroupBy=[
        {'Type': 'DIMENSION', 'Key': 'INSTANCE_TYPE'},
        {'Type': 'DIMENSION', 'Key': 'REGION'}
    ],
    Metrics=['AmortizedCost', 'UnblendedCost', 'UsageQuantity']
)

This won't give you the SP-specific utilization metrics (commitment, savings), but it will show you SP-covered costs broken down by instance type and region.

Option 3: GetSavingsPlansUtilizationDetails + Post-Processing

Use INSTANCE_TYPE_FAMILY as the filter, then correlate with GetCostAndUsage data to break down within the family:

# Get SP utilization by family
sp_util = ce.get_savings_plans_utilization_details(
    TimePeriod={'Start': '2024-05-01', 'End': '2024-05-17'},
    Filter={
        'Dimensions': {
            'Key': 'INSTANCE_TYPE_FAMILY',
            'Values': ['m6g']
        }
    }
)

Then join with CUR or GetCostAndUsage data to get instance-level granularity within that family.

Summary

API	INSTANCE_TYPE Support	SP Utilization Metrics
GetSavingsPlansUtilizationDetails	No (INSTANCE_TYPE_FAMILY only)	Yes
GetCostAndUsage (SavingsPlanCoveredUsage)	Yes (GroupBy)	Partial (costs only)
CUR + Athena	Yes	Yes (full granularity)

CUR + Athena is the recommended approach for instance-type-level Savings Plans analysis.

References:

• GetSavingsPlansUtilizationDetails API Reference
• AWS Cost and Usage Report User Guide
• Understanding your Savings Plans CUR columns