Find the Size of Each S3 Bucket and the Largest One

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListBucketsAndReadStorageMetrics",
      "Effect": "Allow",
      "Action": [
        "s3:ListAllMyBuckets",
        "cloudwatch:ListMetrics",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ExactSizeForOneBucket",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::my-bucket"
    }
  ]
}

// s3-bucket-sizes.ts
// Reports the size of every S3 bucket from the CloudWatch BucketSizeBytes metric
// and names the largest one. Pass --exact <bucket> to sum object sizes instead.
import { S3Client, paginateListBuckets, paginateListObjectsV2 } from "@aws-sdk/client-s3";
import {
  CloudWatchClient,
  paginateListMetrics,
  GetMetricDataCommand,
  type Metric,
} from "@aws-sdk/client-cloudwatch";

const DEFAULT_REGION = process.env.AWS_REGION ?? "us-east-1";

function formatBytes(bytes: number): string {
  const units = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
  let value = bytes;
  let unit = 0;
  while (value >= 1024 && unit < units.length - 1) {
    value /= 1024;
    unit++;
  }
  return `${value.toFixed(unit === 0 ? 0 : 2)} ${units[unit]}`;
}

function bucketOf(metric: Metric | undefined): string | undefined {
  return metric?.Dimensions?.find((d) => d.Name === "BucketName")?.Value;
}

// Group bucket names by the region they live in (ListBuckets returns BucketRegion).
async function bucketsByRegion(): Promise<Map<string, string[]>> {
  const s3 = new S3Client({ region: DEFAULT_REGION });
  const byRegion = new Map<string, string[]>();
  for await (const page of paginateListBuckets({ client: s3 }, {})) {
    for (const bucket of page.Buckets ?? []) {
      if (!bucket.Name) continue;
      const region = bucket.BucketRegion ?? DEFAULT_REGION;
      byRegion.set(region, [...(byRegion.get(region) ?? []), bucket.Name]);
    }
  }
  return byRegion;
}

// Latest daily BucketSizeBytes per bucket in one region, summed over storage classes.
async function sizesInRegion(region: string, buckets: string[]): Promise<Map<string, number>> {
  const cloudwatch = new CloudWatchClient({ region });
  const wanted = new Set(buckets);

  // One metric exists per bucket and storage type (StandardStorage, StandardIAStorage, ...).
  const metrics: Metric[] = [];
  for await (const page of paginateListMetrics(
    { client: cloudwatch },
    { Namespace: "AWS/S3", MetricName: "BucketSizeBytes" },
  )) {
    for (const m of page.Metrics ?? []) {
      const name = bucketOf(m);
      if (name && wanted.has(name)) metrics.push(m);
    }
  }

  const sizes = new Map<string, number>(buckets.map((b) => [b, 0]));
  const end = new Date();
  const start = new Date(end.getTime() - 3 * 24 * 60 * 60 * 1000); // the metric is daily

  for (let i = 0; i < metrics.length; i += 500) {
    const batch = metrics.slice(i, i + 500);
    let nextToken: string | undefined;
    do {
      const res = await cloudwatch.send(
        new GetMetricDataCommand({
          StartTime: start,
          EndTime: end,
          ScanBy: "TimestampDescending",
          NextToken: nextToken,
          MetricDataQueries: batch.map((metric, j) => ({
            Id: `m${i + j}`,
            MetricStat: { Metric: metric, Period: 86400, Stat: "Average" },
          })),
        }),
      );
      for (const result of res.MetricDataResults ?? []) {
        const bucket = bucketOf(metrics[Number(result.Id?.slice(1))]);
        const latest = result.Values?.[0]; // newest first because of ScanBy
        if (bucket && latest !== undefined) sizes.set(bucket, (sizes.get(bucket) ?? 0) + latest);
      }
      nextToken = res.NextToken;
    } while (nextToken);
  }
  return sizes;
}

// Exact size by listing every object (one LIST request per 1,000 objects).
async function exactSize(bucket: string): Promise<void> {
  const s3 = new S3Client({ region: DEFAULT_REGION, followRegionRedirects: true });
  let bytes = 0;
  let objects = 0;
  for await (const page of paginateListObjectsV2({ client: s3 }, { Bucket: bucket })) {
    for (const obj of page.Contents ?? []) {
      bytes += obj.Size ?? 0;
      objects++;
    }
  }
  console.log(`${bucket}: ${formatBytes(bytes)} in ${objects} objects (current versions only)`);
}

async function main(): Promise<void> {
  const exactIndex = process.argv.indexOf("--exact");
  if (exactIndex !== -1) {
    const bucket = process.argv[exactIndex + 1];
    if (!bucket) throw new Error("Usage: --exact <bucket-name>");
    await exactSize(bucket);
    return;
  }

  const rows: { bucket: string; region: string; bytes: number }[] = [];
  for (const [region, buckets] of await bucketsByRegion()) {
    const sizes = await sizesInRegion(region, buckets);
    for (const [bucket, bytes] of sizes) rows.push({ bucket, region, bytes });
  }
  if (rows.length === 0) {
    console.log("No buckets found.");
    return;
  }
  rows.sort((a, b) => b.bytes - a.bytes);

  console.table(rows.map((r) => ({ Bucket: r.bucket, Region: r.region, Size: formatBytes(r.bytes) })));
  const total = rows.reduce((sum, r) => sum + r.bytes, 0);
  console.log(`Total: ${formatBytes(total)} across ${rows.length} buckets`);
  console.log(`Largest: ${rows[0].bucket} (${formatBytes(rows[0].bytes)})`);
}

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

npm install @aws-sdk/client-s3 @aws-sdk/client-cloudwatch
npm install --save-dev tsx typescript

# Every bucket, sized from CloudWatch
AWS_PROFILE=readonly npx tsx s3-bucket-sizes.ts

# Exact size of one bucket by listing its objects
AWS_PROFILE=readonly npx tsx s3-bucket-sizes.ts --exact my-bucket

┌─────────┬──────────────────────────┬──────────────┬─────────────┐
│ (index) │ Bucket                   │ Region       │ Size        │
├─────────┼──────────────────────────┼──────────────┼─────────────┤
│ 0       │ 'acme-backups'           │ 'us-east-1'  │ '4.72 TiB'  │
│ 1       │ 'acme-cloudtrail-logs'   │ 'us-east-1'  │ '612.40 GiB'│
│ 2       │ 'acme-web-assets'        │ 'eu-west-1'  │ '18.03 GiB' │
│ 3       │ 'acme-new-bucket'        │ 'eu-west-1'  │ '0 B'       │
└─────────┴──────────────────────────┴──────────────┴─────────────┘
Total: 5.33 TiB across 4 buckets
Largest: acme-backups (4.72 TiB)