Capacity Reservations & Capacity Blocks for ML

Q: How do I find available Capacity Block time windows?

Call DescribeCapacityBlockOfferings with your instance type, count, and desired duration; it returns specific future start/end dates and their upfront price.

Q: How do I actually use a purchased Capacity Block?

PurchaseCapacityBlock returns a CapacityReservationId. Reference that id in CapacityReservationSpecification on RunInstances when the reserved window arrives.

On-demand availability for large GPU and custom-silicon instance types is not guaranteed. p5, p6, and large Trainium instance types are frequently capacity-constrained, and a training run scheduled for a specific date can fail at the RunInstances call simply because no capacity is free in that AZ at that moment.

AWS offers two SDK-accessible ways to lock in capacity ahead of time: Capacity Reservations, which reserve a type/AZ combination indefinitely starting now, and Capacity Blocks for ML, which reserve GPU/accelerator capacity for a fixed future window.

Recipe

A Capacity Reservation guarantees capacity for a specific instance type in a specific Availability Zone, starting immediately, until you cancel it.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.create_capacity_reservation(
    InstanceType="p5.48xlarge",
    InstancePlatform="Linux/UNIX",
    AvailabilityZone="us-east-1a",
    InstanceCount=4,
    InstanceMatchCriteria="targeted",   # only instances explicitly targeting this reservation use it
)
reservation_id = resp["CapacityReservation"]["CapacityReservationId"]
print(reservation_id)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, CreateCapacityReservationCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new CreateCapacityReservationCommand({
  InstanceType: "p5.48xlarge",
  InstancePlatform: "Linux/UNIX",
  AvailabilityZone: "us-east-1a",
  InstanceCount: 4,
  InstanceMatchCriteria: "targeted",   // only instances explicitly targeting this reservation use it
}));
const reservationId = resp.CapacityReservation?.CapacityReservationId;
console.log(reservationId);

InstanceMatchCriteria: "targeted" means only launches that explicitly reference this reservation consume it - other p5.48xlarge launches in the AZ ignore it. Use "open" instead if any matching instance launched in that AZ should draw from the reservation automatically.

Working Example

Launch into a Capacity Reservation by referencing its id in RunInstances. This is the only change from a normal launch.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.run_instances(
    ImageId="ami-0deeplearning-gpu",
    InstanceType="p5.48xlarge",
    MinCount=4, MaxCount=4,
    Placement={"AvailabilityZone": "us-east-1a"},
    CapacityReservationSpecification={
        "CapacityReservationTarget": {"CapacityReservationId": reservation_id},
    },
)
node_ids = [i["InstanceId"] for i in resp["Instances"]]

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, RunInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new RunInstancesCommand({
  ImageId: "ami-0deeplearning-gpu",
  InstanceType: "p5.48xlarge",
  MinCount: 4, MaxCount: 4,
  Placement: { AvailabilityZone: "us-east-1a" },
  CapacityReservationSpecification: {
    CapacityReservationTarget: { CapacityReservationId: reservationId },
  },
}));
const nodeIds = resp.Instances?.map((i) => i.InstanceId);

With a targeted reservation in place, this launch draws from the reserved pool instead of competing for general on-demand capacity - the whole point of reserving ahead of a planned training run.

Deep Dive

Capacity Blocks for ML: Reserving a Future Time Window

A Capacity Reservation starts now and runs until you cancel it - useful for capacity you need indefinitely, but you still pay for the reservation the entire time, used or not. A Capacity Block for ML instead reserves accelerator capacity for a fixed future time window, which fits the common pattern of a training run scheduled days or weeks ahead.

First, search for available offerings with DescribeCapacityBlockOfferings, specifying the instance type, instance count, and how long you need the capacity.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_capacity_block_offerings(
    InstanceType="p5.48xlarge",
    InstanceCount=8,
    CapacityDurationHours=24,
)
for offering in resp["CapacityBlockOfferings"]:
    print(
        offering["CapacityBlockOfferingId"],
        offering["StartDate"],
        offering["EndDate"],
        offering["UpfrontFee"],
    )

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeCapacityBlockOfferingsCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeCapacityBlockOfferingsCommand({
  InstanceType: "p5.48xlarge",
  InstanceCount: 8,
  CapacityDurationHours: 24,
}));
for (const offering of resp.CapacityBlockOfferings ?? []) {
  console.log(
    offering.CapacityBlockOfferingId,
    offering.StartDate,
    offering.EndDate,
    offering.UpfrontFee,
  );
}

Each offering is a specific future window - a start date, an end date, and an upfront price - for the instance type and count you asked about. Once you find one that fits your schedule, purchase it with PurchaseCapacityBlock.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.purchase_capacity_block(
    CapacityBlockOfferingId="cbo-0abc123",
    InstancePlatform="Linux/UNIX",
)
capacity_reservation_id = resp["CapacityReservation"]["CapacityReservationId"]
print(capacity_reservation_id)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, PurchaseCapacityBlockCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new PurchaseCapacityBlockCommand({
  CapacityBlockOfferingId: "cbo-0abc123",
  InstancePlatform: "Linux/UNIX",
}));
const capacityReservationId = resp.CapacityReservation?.CapacityReservationId;
console.log(capacityReservationId);

A purchased Capacity Block shows up as its own Capacity Reservation, so launching into it at the reserved start time uses the same CapacityReservationSpecification pattern shown above - reference the returned CapacityReservationId on RunInstances.

Choosing Between the Two

Reach for a plain Capacity Reservation when you need a type/AZ guaranteed indefinitely - an always-on serving fleet, or capacity you plan to use starting immediately and releasing whenever the project ends. Reach for a Capacity Block for ML when you know the shape of a specific future training run (instance count, duration, rough start date) and want AWS to guarantee that exact window rather than paying for open-ended reserved capacity.

Gotchas

Reserved capacity still bills. A Capacity Reservation bills for the reserved instances whether or not you launch anything into it; release it (CancelCapacityReservation) when no longer needed.
open vs targeted match criteria matters. An open reservation is silently consumed by any matching launch in the AZ, which can mean a launch you did not intend draws from - or exhausts - your reserved capacity.
Capacity Blocks are pay-upfront. PurchaseCapacityBlock commits to the offering's upfront fee at purchase time, not at usage time.
The AZ is fixed at reservation time. A Capacity Reservation or Capacity Block guarantees capacity in one specific AZ; it does not help if your workload needs flexibility across AZs.
Offerings change with market demand. DescribeCapacityBlockOfferings results reflect current AWS-side availability and can differ significantly by instance type, count, and requested duration.

Alternatives

On-Demand without a reservation is simplest and cheapest when the instance type is not capacity-constrained in your target AZ - reserve only when you have actually hit availability failures or have a hard-scheduled training date.
Spot capacity can supply GPU/accelerator instances at a discount for interruptible or checkpointed training, trading availability guarantees for lower cost.
A different region or AZ may simply have available capacity without needing any reservation, worth checking with DescribeInstanceTypeOfferings before reserving.

Reserve ahead of time when a training run's date and instance count are known and the instance type is scarce; otherwise plain on-demand or Spot is usually simpler and cheaper.

FAQs

What is the difference between a Capacity Reservation and a Capacity Block?

A Capacity Reservation guarantees capacity starting now until you cancel it. A Capacity Block for ML guarantees GPU/accelerator capacity for a fixed future time window that you purchase in advance.

How do I find available Capacity Block time windows?

Call DescribeCapacityBlockOfferings with your instance type, count, and desired duration; it returns specific future start/end dates and their upfront price.

How do I actually use a purchased Capacity Block?

PurchaseCapacityBlock returns a CapacityReservationId. Reference that id in CapacityReservationSpecification on RunInstances when the reserved window arrives.

What does InstanceMatchCriteria control?

Whether any matching instance launched in the AZ automatically consumes the reservation (open) or only instances that explicitly target the reservation id do (targeted).

Do I pay for a Capacity Reservation if I never launch an instance into it?

Yes. The reservation bills for the reserved capacity regardless of usage; cancel it with CancelCapacityReservation when you no longer need it.

When should I use a Capacity Block instead of a plain reservation?

When you have a specific, scheduled future training run with a known instance count and duration, rather than an ongoing need for guaranteed capacity.

Can I reserve capacity across multiple Availability Zones with one call?

No. Both a Capacity Reservation and a Capacity Block are scoped to a single AZ; reserve separately per AZ if your workload needs multi-AZ capacity.

P5/P6 GPU Instances for Large-Scale Training - the instance type most likely to need a reservation ahead of a training run.
Trainium for Cost-Efficient Training - another accelerator family with scarce large-scale capacity.
Choosing AI Compute: GPUs vs Trainium/Inferentia - where capacity availability fits into the accelerator decision.
AI Infrastructure via SDK Best Practices - capacity planning habits for accelerator-heavy workloads.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Recipe

A Capacity Reservation guarantees capacity for a specific instance type in a specific Availability Zone, starting immediately, until you cancel it.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.create_capacity_reservation(
    InstanceType="p5.48xlarge",
    InstancePlatform="Linux/UNIX",
    AvailabilityZone="us-east-1a",
    InstanceCount=4,
    InstanceMatchCriteria="targeted",   # only instances explicitly targeting this reservation use it
)
reservation_id = resp["CapacityReservation"]["CapacityReservationId"]
print(reservation_id)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, CreateCapacityReservationCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new CreateCapacityReservationCommand({
  InstanceType: "p5.48xlarge",
  InstancePlatform: "Linux/UNIX",
  AvailabilityZone: "us-east-1a",
  InstanceCount: 4,
  InstanceMatchCriteria: "targeted",   // only instances explicitly targeting this reservation use it
}));
const reservationId = resp.CapacityReservation?.CapacityReservationId;
console.log(reservationId);

Working Example

Launch into a Capacity Reservation by referencing its id in RunInstances. This is the only change from a normal launch.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.run_instances(
    ImageId="ami-0deeplearning-gpu",
    InstanceType="p5.48xlarge",
    MinCount=4, MaxCount=4,
    Placement={"AvailabilityZone": "us-east-1a"},
    CapacityReservationSpecification={
        "CapacityReservationTarget": {"CapacityReservationId": reservation_id},
    },
)
node_ids = [i["InstanceId"] for i in resp["Instances"]]

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, RunInstancesCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new RunInstancesCommand({
  ImageId: "ami-0deeplearning-gpu",
  InstanceType: "p5.48xlarge",
  MinCount: 4, MaxCount: 4,
  Placement: { AvailabilityZone: "us-east-1a" },
  CapacityReservationSpecification: {
    CapacityReservationTarget: { CapacityReservationId: reservationId },
  },
}));
const nodeIds = resp.Instances?.map((i) => i.InstanceId);

With a targeted reservation in place, this launch draws from the reserved pool instead of competing for general on-demand capacity - the whole point of reserving ahead of a planned training run.

Deep Dive

Capacity Blocks for ML: Reserving a Future Time Window

First, search for available offerings with DescribeCapacityBlockOfferings, specifying the instance type, instance count, and how long you need the capacity.

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.describe_capacity_block_offerings(
    InstanceType="p5.48xlarge",
    InstanceCount=8,
    CapacityDurationHours=24,
)
for offering in resp["CapacityBlockOfferings"]:
    print(
        offering["CapacityBlockOfferingId"],
        offering["StartDate"],
        offering["EndDate"],
        offering["UpfrontFee"],
    )

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, DescribeCapacityBlockOfferingsCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new DescribeCapacityBlockOfferingsCommand({
  InstanceType: "p5.48xlarge",
  InstanceCount: 8,
  CapacityDurationHours: 24,
}));
for (const offering of resp.CapacityBlockOfferings ?? []) {
  console.log(
    offering.CapacityBlockOfferingId,
    offering.StartDate,
    offering.EndDate,
    offering.UpfrontFee,
  );
}

# --- Python (boto3) ---
import boto3
 
ec2 = boto3.client("ec2", region_name="us-east-1")
resp = ec2.purchase_capacity_block(
    CapacityBlockOfferingId="cbo-0abc123",
    InstancePlatform="Linux/UNIX",
)
capacity_reservation_id = resp["CapacityReservation"]["CapacityReservationId"]
print(capacity_reservation_id)

// --- TypeScript (AWS SDK v3) ---
import { EC2Client, PurchaseCapacityBlockCommand } from "@aws-sdk/client-ec2";
 
const ec2 = new EC2Client({ region: "us-east-1" });
const resp = await ec2.send(new PurchaseCapacityBlockCommand({
  CapacityBlockOfferingId: "cbo-0abc123",
  InstancePlatform: "Linux/UNIX",
}));
const capacityReservationId = resp.CapacityReservation?.CapacityReservationId;
console.log(capacityReservationId);

Choosing Between the Two

Gotchas

Reserved capacity still bills. A Capacity Reservation bills for the reserved instances whether or not you launch anything into it; release it (CancelCapacityReservation) when no longer needed.
open vs targeted match criteria matters. An open reservation is silently consumed by any matching launch in the AZ, which can mean a launch you did not intend draws from - or exhausts - your reserved capacity.
Capacity Blocks are pay-upfront. PurchaseCapacityBlock commits to the offering's upfront fee at purchase time, not at usage time.
The AZ is fixed at reservation time. A Capacity Reservation or Capacity Block guarantees capacity in one specific AZ; it does not help if your workload needs flexibility across AZs.
Offerings change with market demand. DescribeCapacityBlockOfferings results reflect current AWS-side availability and can differ significantly by instance type, count, and requested duration.

Alternatives

On-Demand without a reservation is simplest and cheapest when the instance type is not capacity-constrained in your target AZ - reserve only when you have actually hit availability failures or have a hard-scheduled training date.
Spot capacity can supply GPU/accelerator instances at a discount for interruptible or checkpointed training, trading availability guarantees for lower cost.
A different region or AZ may simply have available capacity without needing any reservation, worth checking with DescribeInstanceTypeOfferings before reserving.

Reserve ahead of time when a training run's date and instance count are known and the instance type is scarce; otherwise plain on-demand or Spot is usually simpler and cheaper.

FAQs

What is the difference between a Capacity Reservation and a Capacity Block?

A Capacity Reservation guarantees capacity starting now until you cancel it. A Capacity Block for ML guarantees GPU/accelerator capacity for a fixed future time window that you purchase in advance.

How do I find available Capacity Block time windows?

Call DescribeCapacityBlockOfferings with your instance type, count, and desired duration; it returns specific future start/end dates and their upfront price.

How do I actually use a purchased Capacity Block?

PurchaseCapacityBlock returns a CapacityReservationId. Reference that id in CapacityReservationSpecification on RunInstances when the reserved window arrives.

What does InstanceMatchCriteria control?

Whether any matching instance launched in the AZ automatically consumes the reservation (open) or only instances that explicitly target the reservation id do (targeted).

Do I pay for a Capacity Reservation if I never launch an instance into it?

Yes. The reservation bills for the reserved capacity regardless of usage; cancel it with CancelCapacityReservation when you no longer need it.

When should I use a Capacity Block instead of a plain reservation?

When you have a specific, scheduled future training run with a known instance count and duration, rather than an ongoing need for guaranteed capacity.

Can I reserve capacity across multiple Availability Zones with one call?

No. Both a Capacity Reservation and a Capacity Block are scoped to a single AZ; reserve separately per AZ if your workload needs multi-AZ capacity.

P5/P6 GPU Instances for Large-Scale Training - the instance type most likely to need a reservation ahead of a training run.
Trainium for Cost-Efficient Training - another accelerator family with scarce large-scale capacity.
Choosing AI Compute: GPUs vs Trainium/Inferentia - where capacity availability fits into the accelerator decision.
AI Infrastructure via SDK Best Practices - capacity planning habits for accelerator-heavy workloads.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Capacity Reservations & Capacity Blocks for ML

Search Documentation

Capacity Reservations & Capacity Blocks for ML