# SageMaker training plans creation using the SageMaker API, or AWS CLI
SageMaker training plans support the programmatic creation of training plans through its API. You can interact with the training plans API using the AWS CLI or SageMaker SDKs.
SageMaker training plans's API actions provide a comprehensive workflow for managing training plans programmatically:
+ **`SearchTrainingPlanOfferings`:** Enables users to query and discover available compute resources by specifying parameters like instance type, count, and desired time window. The API returns a ranked list of training plan offerings that best match the user's requirements.
+ **`CreateTrainingPlan`:** Allows reservation of a specific training plan offering, transforming a potential compute capacity into scheduled reserved capacities with a unique training plan ARN.
+ **`ListTrainingPlans`:** Provides a method to retrieve and review all existing training plans in a user's AWS account, with optional filtering and sorting capabilities.
+ **`DescribeTrainingPlan`:** Offers detailed insights into a specific training plan, including its lifecycle stages from `Pending` to `Active` to `Expired`.
+ **`ExtendTrainingPlan`:** Extends an existing training plan by purchasing an extension offering. For more information, see [Training plans extension](training-plan-extension.md).
+ **`DescribeTrainingPlanExtensionHistory`:** Retrieves the extension history for a training plan. For more information, see [Training plans extension](training-plan-extension.md).
**Topics**
+ [Search training plan offerings](search-training-plan-offerings-api-cli-sdk.md)
+ [Reserve the best training plan](choose-best-training-plan-using-api-cli-sdk.md)
+ [List training plans](list-training-plans-using-api-cli-sdk.md)
+ [View training plan details](training-plan-details-using-api-cli-sdk.md)
# Search training plan offerings
To create a training plan, start by calling the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html) API operation, passing your plan requirements (such as instance type, count, and desired time window) as input parameters. Training plans are specific to their target resource. Ensure that you specify which target resource the plan will be used for (`training-job` or `hyperpod-cluster`). The API returns a list of available offerings that match your requirements. If no suitable offerings are found, you may need to adjust your requirements and search again.
This API call retrieves the training plan offerings that best meet your capacity needs. Each [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanOffering.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanOffering.html) returned in the response is identified by a unique offering ID. The first offering in the list represents the best match for your requirements. If no suitable training plan is available within your specified dates, the list is empty. Adjust your search criteria and look for a new set of offerings.
+ Reservation durations are available in 1-day increments from 1 to 182 days.
+ The reservation instance quantity options are 1, 2, 4, 8, 16, 32 or 64 instances.
To learn about the list of available instances supported by SageMaker training plans, see [Supported instance types, AWS Regions, and pricing](reserve-capacity-with-training-plans.md#training-plans-supported-instances-and-regions).
The following example uses an AWS CLI command to request training plan offerings with a specified instance type, count, and time information.
```
# List training plan offerings with instance type, instance count, duration in hours, start time after, and end time before.
aws sagemaker search-training-plan-offerings \
--target-resources "training-job" \
--instance-type "ml.p4d.24xlarge" \
--instance-count 1 \
--duration-hours 15 \
--start-time-after "1737484800"
--end-time-before "1737657600"
```
This JSON document is a sample response from the SageMaker training plans API. The response provides information about multiple available training plan offerings that match the specified capacity requirements. It includes three distinct offerings with varying durations, upfront fees, and start/end times, all using the same instance type and targeting training jobs.
```
{
"TrainingPlanOfferings": [
{
"TrainingPlanOfferingId": "tpo-SHA-256-hash-value",
"TargetResources": [
"training-job"
],
"RequestedStartTimeAfter": "2025-01-21T11:08:27.704000-08:00",
"DurationHours": 15,
"DurationMinutes": 51,
"UpfrontFee": "xxxx.xx",
"CurrencyCode": "USD",
"ReservedCapacityOfferings": [
{
"InstanceType": "ml.p4d.24xlarge",
"InstanceCount": 1,
"AvailabilityZone": "us-west-2a",
"DurationHours": 15,
"DurationMinutes": 51,
"StartTime": "2025-01-21T11:39:00-08:00",
"EndTime": "2025-01-22T03:30:00-08:00"
}
]
},
{
"TrainingPlanOfferingId": "tpo-SHA-256-hash-value",
"TargetResources": [
"training-job"
],
"RequestedStartTimeAfter": "2025-01-21T11:08:27.704000-08:00",
"DurationHours": 39,
"DurationMinutes": 51,
"UpfrontFee": "xxxx.xx",
"CurrencyCode": "USD",
"ReservedCapacityOfferings": [
{
"InstanceType": "ml.p4d.24xlarge",
"InstanceCount": 1,
"AvailabilityZone": "us-west-2a",
"DurationHours": 39,
"DurationMinutes": 51,
"StartTime": "2025-01-21T11:39:00-08:00",
"EndTime": "2025-01-23T03:30:00-08:00"
}
]
},
{
"TrainingPlanOfferingId": "tpo-SHA-256-hash-value",
"TargetResources": [
"training-job"
],
"RequestedStartTimeAfter": "2025-01-21T11:08:27.704000-08:00",
"DurationHours": 24,
"DurationMinutes": 0,
"UpfrontFee": "xxxx.xx",
"CurrencyCode": "USD",
"ReservedCapacityOfferings": [
{
"InstanceType": "ml.p4d.24xlarge",
"InstanceCount": 1,
"AvailabilityZone": "us-west-2a",
"DurationHours": 24,
"DurationMinutes": 0,
"StartTime": "2025-01-22T03:30:00-08:00",
"EndTime": "2025-01-23T03:30:00-08:00"
}
]
}
]
}
```
The following is a sample command of how to use the AWS CLI to search for training plan offerings that include UltraServers.
```
aws sagemaker search-training-plan-offerings \
--ultra-server-type ml.c6i-32xlargesc \
--ultra-server-count 1 \
--duration-hours 24 \
--target-resources hyperpod-cluster
--start-time-after "1737484800" \
--end-time-before "1737657600"
```
```
{
"TrainingPlanOfferings": [
{
"TrainingPlanOfferingId": "tpo-SHA-256-hash-value",
"TargetResources": [
"training-job"
],
"RequestedStartTimeAfter": "2025-07-21T16:59:25.760000+00:00",
"DurationHours": 24,
"DurationMinutes": 0,
"UpfrontFee": "0.24",
"CurrencyCode": "USD",
"ReservedCapacityOfferings": [
{
"ReservedCapacityType": "UltraServer",
"UltraServerType": "ml.u-p6e-gb200x72",
"UltraServerCount": 1,
"InstanceType": "ml.p6e-gb200.36xlarge",
"InstanceCount": 18,
"AvailabilityZone": "us-east-2a",
"DurationHours": 24,
"DurationMinutes": 0,
"StartTime": "2025-07-22T11:30:00+00:00",
"EndTime": "2025-07-23T11:30:00+00:00"
}
]
}
]
}
```
The following sections define the mandatory and optional input request parameters for the `SearchTrainingPlanOfferings` API operation.
## Required parameters
When calling the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_SearchTrainingPlanOfferings.html) API to list training plan offerings that meet your requirements, you must provide the following values:
+ `TargetResources`: The target resources (`training-job` or `hyperpod-cluster`) for which the plan will be used. The default value is `training-job`. Training plans are specific to their target resource.
+ A training plan designed for SageMaker training jobs can only be used to schedule and run training jobs.
+ A training plan for HyperPod clusters can be used exclusively to provide compute resources to a cluster's instance group.
+ `InstanceType`: The type of instance to provision. The `InstanceType` must be of a supported type.
To learn about the list of available instances supported by SageMaker training plans, see [Supported instance types, AWS Regions, and pricing](reserve-capacity-with-training-plans.md#training-plans-supported-instances-and-regions).
+ `InstanceCount`: The number of instances to provision. If the number of instances is greater than 1, it should be a power of 2.
+ `DurationHour`: The total duration of your requested plan in hours. The `DurationHour` is rounded up to the nearest multiple of 24.
## Optional parameters
The following sections provide details on some optional parameters that you can pass to your `SearchTrainingPlanOfferings` API request.
+ `StartTimeAfter`: Specify the requested start time of the plan. The `StartTimeAfter` should be a `timestamp` or an `ISO 8601 date/time` value in the future.
+ `EndTimeBefore`: Specify the requested end time of the plan in a `timestamp` or an `ISO 8601 date/time` format. The `EndTimeBefore` should be at least 24 hours after the start time .
+ `UltraServerType` : Specify the type of UltraServer to search for. For more information about UltraServers, see [UltraServers in SageMaker AI](reserve-capacity-with-training-plans.md#training-plans-ultraservers).
+ `UltraServerCount`: Specify the number of UltraServers to search for.
# Reserve the best training plan
After reviewing the available training plan offerings that best match your requirements, you can reserve a specific plan by calling the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html) API operation. When created, the plan initially enters a `Pending` state and remains there until the reservation process is complete. The response to the API call returns a training plan Amazon Resource Name (ARN). Make a note of this ARN for tracking and monitoring purposes later on. The training plan reservation is fulfilled asynchronously in the backend. The payment for the total amount is automatically collected as part of the fulfillment process. Once the payment transaction is completed and the requested reserved capacities are secured, the training plan is set to the `Scheduled` state, and is ready for scheduling.
**Important**
Training plans cannot be modified once purchased.
Training plans cannot be shared across AWS accounts or within your AWS Organization.
The following example uses the an AWS CLI command to request a specific training plan, passing the plan ID as a parameter.
```
aws sagemaker create-training-plan \
--training-plan-offering-id "tpo-SHA-256-hash-value" \
--training-plan-name "name" \
```
This JSON document is a sample response from the SageMaker training plans API. The response contains the Amazon Resource Name (ARN) of the training plan that has been successfully created.
**Note**
The training plan remains in a `Pending` status until the fulfillment process is complete.
```
{
"TrainingPlanArn":"arn:aws:sagemaker:us-east-1:123456789123:training-plan/large-models-fine-tuning"
}
```
The following sections define the mandatory and optional input request parameters for the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html) API operation.
## Required parameters
When calling [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingPlan.html) API to reserve a particular training plan, you must provide the following values:
+ `TrainingPlanOfferingId`: The ID of the plan you are choosing. You can retrieve the ID of a plan offering in the response of your `SearchTrainingPlanOfferings` API call. Its format should start with `pto-*`.
+ `TrainingPlanName`: The name of the plan you are creating.
# List training plans
You can list all the training plans that have been created in your AWS account and Region by calling the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingPlans.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ListTrainingPlans.html) API.
The following example uses an AWS CLI command to retrieve the list of your training plans.
```
aws sagemaker list-training-plans \
--start-time-after "2024-09-26T00:00:01.000Z"
```
This JSON document is a sample response from the SageMaker training plans API. The response provides details about one training plan that has been successfully created and reserved.
```
{
"[TrainingPlanSummaries](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanSummary.html)": [
{
"AvailableInstanceCount": 2,
"CurrencyCode": "USD",
"DurationHours": 48,
"DurationMinutes": 0,
"EndTime": "2024-09-28T04:30:00-07:00",
"InUseInstanceCount": 2,
"[ReservedCapacitySummaries](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ReservedCapacitySummary.html)": [
{
"AvailabilityZone": "string",
"DurationHours": 48,
"DurationMinutes": 0,
"EndTime": "2024-09-28T04:30:00-07:00",
"InstanceType": "ml.p5.48xlarge",
"ReservedCapacityArn": "arn:aws:sagemaker:us-east-1:123456789123:reserved-capacity/large-models-fine-tuning-rc1",
"StartTime": "2024-09-26T04:30:00-07:00",
"Status": "Scheduled",
"TotalInstanceCount": 4,
"UltraServerCount": 4,
"UltraServerType": "ml.p6e-gb200.36xlarge"
}
],
"StartTime": "2024-09-26T04:30:00-07:00",
"Status": "Scheduled",
"StatusMessage": "Payment confirmed, training plan scheduled."
"TargetResources": [ "training-job" ],
"TotalInstanceCount": 4,
"TotalUltraServerCount": 4,
"TrainingPlanArn": "arn:aws:sagemaker:us-east-1:123456789123:training-plan/large-models-fine-tuning",
"TrainingPlanName": "large-models-fine-tuning",
"UpfrontFee": "xxxx.xx"
}
]
}
```
The following sections provide details of some optional parameters that you can pass to your `ListTrainingPlans` API request.
## Optional parameters
The following sections provide details on some optional parameters that you can pass to your `ListTrainingPlans` API request.
+ `StartTimeAfter`: The start time of the actual time range of the listed plans, specified as a `timestamp` or an `ISO 8601 date/time`.
+ `StartTimeBefore`: The end time of the actual time range of the listed plans, specified as a `timestamp` or an `ISO 8601 date/time`.
+ `Filters`: Criteria used to filter the results, with up to 5 Name-Value pairs where "Name" is the name of a field of a [TrainingPlanSummary](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TrainingPlanSummary.html) and "Value" is the value to consider for the filter. For example `Name=Status,Value=Active`.
The following example uses an AWS CLI command to retrieve your list of training plans, using some of the optional parameters described above.
```
aws sagemaker list-training-plans --max-results 10 --sort-by StartTime --sort-order Descending --start-time-after 13000000 --filters Name=Status,Value=Active
```
# View training plan details
To monitor the status or retrieve details of a training plan, you can use the [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlan.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrainingPlan.html) API. The API response includes a `Status` field, which reflects the current state of the training plan:
+ If the plan purchase fails, the status is set to `Failed`.
+ Upon successful payment, the status transitions from `Pending` to `Scheduled`, based on the plan's start date.
+ When the plan reaches its start date, the status changes to `Active`.
+ For plans with multiple discontinuous reserved capacities, the status reverts to `Scheduled` between active periods, until the start date of the next reserved capacity.
+ After the plan's end date, the status becomes `Expired`.
Once the status is `Scheduled`, you can utilize the capacity reserved in the plan for your SageMaker training jobs or HyperPod cluster workloads.
**Note**
Training jobs associated with the plan remain in `Pending` status until the plan becomes `Active`.
For HyperPod clusters using a training plan for compute capacity, the instance group status appears as `InService` once created.
The following example uses an AWS CLI command to retrieve the details of a training plan by its name.
```
aws sagemaker describe-training-plan \
--training-plan-name "name"
```
This JSON document is a sample response from the SageMaker training plans API. This response provides details about a training plan that has been successfully created.
```
{
"AvailableInstanceCount": 2,
"CurrencyCode": "USD",
"DurationHours": 48,
"DurationMinutes": 0,
"EndTime": "2024-09-28T04:30:00-07:00",
"InUseInstanceCount": 2,
"[ReservedCapacitySummaries](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ReservedCapacitySummary.html)": [
{
"AvailabilityZone": "string",
"DurationHours": 48,
"DurationMinutes": 0,
"EndTime": "2024-09-28T04:30:00-07:00",
"InstanceType": "ml.p5.48xlarge",
"ReservedCapacityArn": "arn:aws:sagemaker:us-east-1:123456789123:reserved-capacity/large-models-fine-tuning-rc1",
"StartTime": "2024-09-26T04:30:00-07:00",
"Status": "Scheduled",
"TotalInstanceCount": 4,
"UltraServerCount": 4,
"UltraServerType": "ml.p6e-gb200.36xlarge"
}
],
"StartTime": "2024-09-26T04:30:00-07:00",
"Status": "Scheduled",
"StatusMessage": "Payment confirmed, training plan scheduled."
"TargetResources": [ "training-job" ],
"TotalInstanceCount": 4,
"TotalUltraServerCount": 4,
"TrainingPlanArn": "arn:aws:sagemaker:us-east-1:123456789123:training-plan/large-models-fine-tuning",
"TrainingPlanName": "large-models-fine-tuning",
"UpfrontFee": "xxxx.xx"
}
```
The following sections define the mandatory input request parameter for the `DescribeTrainingPlan` API operation.
## Required parameters
+ `TrainingPlanName`: The name of the training plan you want to describe.