CreateTrialCommand

Suggest an Edit

Creates an SageMaker trial. A trial is a set of steps called trial components that produce a machine learning model. A trial is part of a single SageMaker experiment.

When you use SageMaker Studio or the SageMaker Python SDK, all experiments, trials, and trial components are automatically tracked, logged, and indexed. When you use the Amazon Web Services SDK for Python (Boto), you must use the logging APIs provided by the SDK.

You can add tags to a trial and then use the Search  API to search for the tags.

To get a list of all your trials, call the ListTrials  API. To view a trial's properties, call the DescribeTrial  API. To create a trial component, call the CreateTrialComponent  API.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { SageMakerClient, CreateTrialCommand } from "@aws-sdk/client-sagemaker"; // ES Modules import
// const { SageMakerClient, CreateTrialCommand } = require("@aws-sdk/client-sagemaker"); // CommonJS import
const client = new SageMakerClient(config);
const input = { // CreateTrialRequest
  TrialName: "STRING_VALUE", // required
  DisplayName: "STRING_VALUE",
  ExperimentName: "STRING_VALUE", // required
  MetadataProperties: { // MetadataProperties
    CommitId: "STRING_VALUE",
    Repository: "STRING_VALUE",
    GeneratedBy: "STRING_VALUE",
    ProjectId: "STRING_VALUE",
  },
  Tags: [ // TagList
    { // Tag
      Key: "STRING_VALUE", // required
      Value: "STRING_VALUE", // required
    },
  ],
};
const command = new CreateTrialCommand(input);
const response = await client.send(command);
// { // CreateTrialResponse
//   TrialArn: "STRING_VALUE",
// };

CreateTrialCommand Input

See CreateTrialCommandInput for more details

Parameter
Type
Description
ExperimentName
Required
string | undefined

The name of the experiment to associate the trial with.

TrialName
Required
string | undefined

The name of the trial. The name must be unique in your Amazon Web Services account and is not case-sensitive.

DisplayName
string | undefined

The name of the trial as displayed. The name doesn't need to be unique. If DisplayName isn't specified, TrialName is displayed.

MetadataProperties
MetadataProperties | undefined

Metadata properties of the tracking entity, trial, or trial component.

Tags
Tag[] | undefined

A list of tags to associate with the trial. You can use Search  API to search on the tags.

CreateTrialCommand Output

See CreateTrialCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
TrialArn
string | undefined

The Amazon Resource Name (ARN) of the trial.

Throws

Name
Fault
Details
ResourceLimitExceeded
client

You have exceeded an SageMaker resource limit. For example, you might have too many training jobs created.

ResourceNotFound
client

Resource being access is not found.

SageMakerServiceException
Base exception class for all service exceptions from SageMaker service.