Check Savings Plans Coverage and Utilization

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadSavingsPlansReports",
      "Effect": "Allow",
      "Action": [
        "ce:GetSavingsPlansCoverage",
        "ce:GetSavingsPlansUtilization",
        "ce:GetSavingsPlansPurchaseRecommendation"
      ],
      "Resource": "*"
    }
  ]
}

// savings-plans-report.ts
// Savings Plans coverage and utilization report from Cost Explorer: monthly coverage, uncovered On-Demand spend
// by service, monthly utilization, and (with --recommend) AWS's purchase recommendation summary.
// Read-only. Every Cost Explorer API request is billed ($0.01 each); the script prints how many it made.
// Usage: npx tsx savings-plans-report.ts [--months 3] [--recommend COMPUTE_SP|EC2_INSTANCE_SP|SAGEMAKER_SP|DATABASE_SP]
import {
  CostExplorerClient,
  DataUnavailableException,
  GetSavingsPlansCoverageCommand,
  GetSavingsPlansPurchaseRecommendationCommand,
  GetSavingsPlansUtilizationCommand,
  type SupportedSavingsPlansType,
} from "@aws-sdk/client-cost-explorer";

const args = process.argv.slice(2);
const flag = (name: string): string | undefined => {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
};
const months = Number(flag("--months") ?? 3);
const recommend = flag("--recommend") as SupportedSavingsPlansType | undefined;

const ce = new CostExplorerClient({ region: "us-east-1" }); // Cost Explorer's API endpoint is in us-east-1
let requests = 0;
async function call<T>(p: Promise<T>): Promise<T> {
  requests++;
  return p;
}

const day = (d: Date) => d.toISOString().slice(0, 10);
// End is exclusive and must be before the current date, so the report runs up to yesterday.
const endDate = new Date(Date.now() - 86_400_000);
const lastDay = new Date(endDate.getTime() - 86_400_000); // last full day included
const end = day(endDate);
const start = day(new Date(Date.UTC(lastDay.getUTCFullYear(), lastDay.getUTCMonth() - (months - 1), 1)));
const last30 = day(new Date(endDate.getTime() - 30 * 86_400_000));
const usd = (s?: string) => `$${Number(s ?? 0).toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
const pct = (s?: string) => `${Number(s ?? 0).toFixed(1)}%`;

async function coverageByMonth(): Promise<void> {
  const res = await call(ce.send(new GetSavingsPlansCoverageCommand({
    TimePeriod: { Start: start, End: end },
    Granularity: "MONTHLY",
    Metrics: ["SpendCoveredBySavingsPlans"],
  })));
  console.log("\nCoverage by month (Savings Plans-eligible spend only)");
  console.table((res.SavingsPlansCoverages ?? []).map((c) => ({
    Month: c.TimePeriod?.Start?.slice(0, 7),
    Covered: usd(c.Coverage?.SpendCoveredBySavingsPlans),
    OnDemand: usd(c.Coverage?.OnDemandCost),
    Total: usd(c.Coverage?.TotalCost),
    Coverage: pct(c.Coverage?.CoveragePercentage),
  })));
}

// Granularity can't be combined with GroupBy, so this is one total per service for the last 30 days.
async function uncoveredByService(): Promise<void> {
  const rows: { Service: string; OnDemand: number; Coverage: string }[] = [];
  let NextToken: string | undefined;
  do {
    const res = await call(ce.send(new GetSavingsPlansCoverageCommand({
      TimePeriod: { Start: last30, End: end },
      GroupBy: [{ Type: "DIMENSION", Key: "SERVICE" }],
      Metrics: ["SpendCoveredBySavingsPlans"],
      SortBy: { Key: "OnDemandCost", SortOrder: "DESCENDING" },
      MaxResults: 100,
      NextToken,
    })));
    for (const c of res.SavingsPlansCoverages ?? []) {
      rows.push({
        Service: Object.values(c.Attributes ?? {}).join(" "), // the grouped SERVICE value
        OnDemand: Number(c.Coverage?.OnDemandCost ?? 0),
        Coverage: pct(c.Coverage?.CoveragePercentage),
      });
    }
    NextToken = res.NextToken;
  } while (NextToken);
  console.log(`\nOn-Demand spend not covered, last 30 days (${last30} to ${end}), by service`);
  console.table(rows.filter((r) => r.OnDemand > 0).map((r) => ({ ...r, OnDemand: usd(String(r.OnDemand)) })));
}

async function utilizationByMonth(): Promise<void> {
  try {
    const res = await call(ce.send(new GetSavingsPlansUtilizationCommand({
      TimePeriod: { Start: start, End: end },
      Granularity: "MONTHLY",
    })));
    console.log("\nUtilization by month");
    console.table((res.SavingsPlansUtilizationsByTime ?? []).map((u) => ({
      Month: u.TimePeriod?.Start?.slice(0, 7),
      Commitment: usd(u.Utilization?.TotalCommitment),
      Used: usd(u.Utilization?.UsedCommitment),
      Unused: usd(u.Utilization?.UnusedCommitment),
      Utilization: pct(u.Utilization?.UtilizationPercentage),
      NetSavings: usd(u.Savings?.NetSavings),
    })));
    const t = res.Total;
    console.log(`Total: ${pct(t?.Utilization?.UtilizationPercentage)} used, ${usd(t?.Utilization?.UnusedCommitment)} unused, ` +
      `${usd(t?.Savings?.NetSavings)} net savings vs ${usd(t?.Savings?.OnDemandCostEquivalent)} On-Demand equivalent`);
  } catch (err) {
    if (err instanceof DataUnavailableException) console.log("\nUtilization: no Savings Plans data for this period.");
    else throw err;
  }
}

async function recommendation(type: SupportedSavingsPlansType): Promise<void> {
  const res = await call(ce.send(new GetSavingsPlansPurchaseRecommendationCommand({
    SavingsPlansType: type,
    TermInYears: "ONE_YEAR",
    PaymentOption: "NO_UPFRONT",
    LookbackPeriodInDays: "THIRTY_DAYS",
  })));
  const s = res.SavingsPlansPurchaseRecommendation?.SavingsPlansPurchaseRecommendationSummary;
  console.log(`\nRecommendation: ${type}, 1 year, no upfront, 30-day lookback (generated ${res.Metadata?.GenerationTimestamp ?? "n/a"})`);
  if (!s) {
    console.log("No recommendation: not enough eligible On-Demand usage in the lookback period.");
    return;
  }
  console.log(`Commit ${usd(s.HourlyCommitmentToPurchase)}/hour; estimated savings ${usd(s.EstimatedMonthlySavingsAmount)}/month ` +
    `(${pct(s.EstimatedSavingsPercentage)}) on current On-Demand spend of ${usd(s.CurrentOnDemandSpend)}`);
}

async function main(): Promise<void> {
  await coverageByMonth();
  await uncoveredByService();
  await utilizationByMonth();
  if (recommend) await recommendation(recommend);
  console.log(`\n${requests} Cost Explorer API requests made (≈ $${(requests * 0.01).toFixed(2)}). Report only: nothing was purchased.`);
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

npm install @aws-sdk/client-cost-explorer
npm install --save-dev tsx typescript

# Coverage and utilization for the last 3 months
AWS_PROFILE=billing-readonly npx tsx savings-plans-report.ts

# Add AWS's Compute Savings Plans recommendation
AWS_PROFILE=billing-readonly npx tsx savings-plans-report.ts --recommend COMPUTE_SP

# A longer view: the last 12 months (Start must be within 13 months)
AWS_PROFILE=billing-readonly npx tsx savings-plans-report.ts --months 12

Coverage by month (Savings Plans-eligible spend only)
┌─────────┬───────────┬─────────────┬─────────────┬─────────────┬──────────┐
│ (index) │ Month     │ Covered     │ OnDemand    │ Total       │ Coverage │
├─────────┼───────────┼─────────────┼─────────────┼─────────────┼──────────┤
│ 0       │ '2026-07' │ '$6,420.00' │ '$2,580.00' │ '$9,000.00' │ '71.3%'  │
│ 1       │ '2026-08' │ '$6,390.00' │ '$3,310.00' │ '$9,700.00' │ '65.9%'  │
│ 2       │ '2026-09' │ '$5,880.00' │ '$3,020.00' │ '$8,900.00' │ '66.1%'  │
└─────────┴───────────┴─────────────┴─────────────┴─────────────┴──────────┘

On-Demand spend not covered, last 30 days (2026-08-27 to 2026-09-26), by service
┌─────────┬──────────────────────────────────────────┬─────────────┬──────────┐
│ (index) │ Service                                  │ OnDemand    │ Coverage │
├─────────┼──────────────────────────────────────────┼─────────────┼──────────┤
│ 0       │ 'Amazon Elastic Compute Cloud - Compute' │ '$2,140.00' │ '69.8%'  │
│ 1       │ 'AWS Lambda'                             │ '$610.00'   │ '12.4%'  │
│ 2       │ 'Amazon Elastic Container Service'       │ '$270.00'   │ '0.0%'   │
└─────────┴──────────────────────────────────────────┴─────────────┴──────────┘

Utilization by month
┌─────────┬───────────┬─────────────┬─────────────┬───────────┬─────────────┬─────────────┐
│ (index) │ Month     │ Commitment  │ Used        │ Unused    │ Utilization │ NetSavings  │
├─────────┼───────────┼─────────────┼─────────────┼───────────┼─────────────┼─────────────┤
│ 0       │ '2026-07' │ '$3,720.00' │ '$3,720.00' │ '$0.00'   │ '100.0%'    │ '$2,700.00' │
│ 1       │ '2026-08' │ '$3,720.00' │ '$3,690.24' │ '$29.76'  │ '99.2%'     │ '$2,699.76' │
│ 2       │ '2026-09' │ '$3,240.00' │ '$2,991.60' │ '$248.40' │ '92.3%'     │ '$2,640.00' │
└─────────┴───────────┴─────────────┴─────────────┴───────────┴─────────────┴─────────────┘
Total: 97.4% used, $278.16 unused, $8,039.76 net savings vs $18,719.76 On-Demand equivalent

Recommendation: COMPUTE_SP, 1 year, no upfront, 30-day lookback (generated 2026-09-26T08:14:52Z)
Commit $1.20/hour; estimated savings $251.40/month (24.8%) on current On-Demand spend of $1,013.50

4 Cost Explorer API requests made (≈ $0.04). Report only: nothing was purchased.