Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

StartNotebookRun

Starts a notebook run in Amazon SageMaker Unified Studio. A notebook run represents the execution of an Amazon SageMaker notebook within a project. You can configure compute, network, timeout, and environment settings for the run.

Request Syntax


POST /v2/domains/domainIdentifier/notebook-runs HTTP/1.1
Content-type: application/json

{
   "clientToken": "string",
   "computeConfiguration": { 
      "environmentVersion": "string",
      "instanceType": "string"
   },
   "metadata": { 
      "string" : "string" 
   },
   "networkConfiguration": { 
      "networkAccessType": "string",
      "securityGroupIds": [ "string" ],
      "subnetIds": [ "string" ],
      "vpcId": "string"
   },
   "notebookIdentifier": "string",
   "owningProjectIdentifier": "string",
   "parameters": { 
      "string" : "string" 
   },
   "scheduleIdentifier": "string",
   "timeoutConfiguration": { 
      "runTimeoutInMinutes": number
   },
   "triggerSource": { 
      "name": "string",
      "type": "string"
   }
}

URI Request Parameters

The request uses the following URI parameters.

domainIdentifier

The identifier of the Amazon SageMaker Unified Studio domain in which the notebook run is started.

Pattern: dzd[-_][a-zA-Z0-9_-]{1,36}

Required: Yes

Request Body

The request accepts the following data in JSON format.

clientToken

A unique, case-sensitive identifier to ensure idempotency of the request. This field is automatically populated if not provided.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\x21-\x7E]+

Required: No

computeConfiguration

The compute configuration for the notebook run, including instance type and environment version.

Type: ComputeConfig object

Required: No

metadata

The metadata for the notebook run, specified as key-value pairs. You can specify up to 50 entries, with keys up to 128 characters and values up to 1024 characters.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 0. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

networkConfiguration

The network configuration for the notebook run, including network access type and optional VPC settings.

Type: NetworkConfig object

Required: No

notebookIdentifier

The identifier of the notebook to run.

Type: String

Pattern: [a-zA-Z0-9_-]{1,36}

Required: Yes

owningProjectIdentifier

The identifier of the project that owns the notebook run.

Type: String

Pattern: [a-zA-Z0-9_-]{1,36}

Required: Yes

parameters

The sensitive parameters for the notebook run, specified as key-value pairs. You can specify up to 50 entries, with keys up to 128 characters and values up to 1024 characters.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 0. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 1024.

Required: No

scheduleIdentifier

The identifier of the schedule associated with the notebook run.

Type: String

Pattern: [a-zA-Z0-9_-]{1,36}

Required: No

timeoutConfiguration

The timeout configuration for the notebook run. The default timeout is 720 minutes (12 hours) and the maximum is 1440 minutes (24 hours).

Type: TimeoutConfig object

Required: No

triggerSource

The source that triggered the notebook run.

Type: TriggerSource object

Required: No

Response Syntax


HTTP/1.1 201
Content-type: application/json

{
   "cellOrder": [ 
      { 
      }
   ],
   "completedAt": number,
   "computeConfiguration": { 
      "environmentVersion": "string",
      "instanceType": "string"
   },
   "createdAt": number,
   "createdBy": "string",
   "domainId": "string",
   "environmentConfiguration": { 
      "imageVersion": "string",
      "packageConfig": { 
         "packageManager": "string",
         "packageSpecification": "string"
      }
   },
   "error": { 
      "message": "string"
   },
   "id": "string",
   "metadata": { 
      "string" : "string" 
   },
   "networkConfiguration": { 
      "networkAccessType": "string",
      "securityGroupIds": [ "string" ],
      "subnetIds": [ "string" ],
      "vpcId": "string"
   },
   "notebookId": "string",
   "owningProjectId": "string",
   "parameters": { 
      "string" : "string" 
   },
   "scheduleId": "string",
   "startedAt": number,
   "status": "string",
   "storageConfiguration": { 
      "kmsKeyArn": "string",
      "projectS3Path": "string"
   },
   "timeoutConfiguration": { 
      "runTimeoutInMinutes": number
   },
   "triggerSource": { 
      "name": "string",
      "type": "string"
   },
   "updatedAt": number,
   "updatedBy": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 201 response.

The following data is returned in JSON format by the service.

cellOrder

The ordered list of cells in the notebook run.

Type: Array of CellInformation objects

Array Members: Minimum number of 0 items. Maximum number of 200 items.

completedAt

The timestamp of when the notebook run completed.

Type: Timestamp

computeConfiguration

The compute configuration of the notebook run.

Type: ComputeConfig object

createdAt

The timestamp of when the notebook run was created.

Type: Timestamp

createdBy

The identifier of the user who created the notebook run.

Type: String

domainId

The identifier of the Amazon SageMaker Unified Studio domain.

Type: String

Pattern: dzd[-_][a-zA-Z0-9_-]{1,36}

environmentConfiguration

The environment configuration of the notebook run, including image version and package settings.

Type: EnvironmentConfig object

error

The error details if the notebook run failed.

Type: NotebookRunError object

id

The identifier of the notebook run.

Type: String

Pattern: [a-zA-Z0-9_-]{1,36}

metadata

The metadata of the notebook run.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 0. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 1024.

networkConfiguration

The network configuration of the notebook run.

Type: NetworkConfig object

notebookId

The identifier of the notebook.

Type: String

Pattern: [a-zA-Z0-9_-]{1,36}

owningProjectId

The identifier of the project that owns the notebook run.

Type: String

Pattern: [a-zA-Z0-9_-]{1,36}

parameters

The sensitive parameters of the notebook run.

Type: String to string map

Map Entries: Minimum number of 0 items. Maximum number of 50 items.

Key Length Constraints: Minimum length of 0. Maximum length of 128.

Value Length Constraints: Minimum length of 0. Maximum length of 1024.

scheduleId

The identifier of the schedule associated with the notebook run.

Type: String

Pattern: [a-zA-Z0-9_-]{1,36}

startedAt

The timestamp of when the notebook run started executing.

Type: Timestamp

status

The status of the notebook run.

Type: String

storageConfiguration

The storage configuration of the notebook run, including the Amazon Simple Storage Service path and AWS KMS key ARN.

Type: StorageConfig object

timeoutConfiguration

The timeout configuration of the notebook run.

Type: TimeoutConfig object

triggerSource

The source that triggered the notebook run.

Type: TriggerSource object

updatedAt

The timestamp of when the notebook run was last updated.

Type: Timestamp

updatedBy

The identifier of the user who last updated the notebook run.

Type: String

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

ConflictException

There is a conflict while performing this action.

HTTP Status Code: 409

InternalServerException

The request has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource cannot be found.

HTTP Status Code: 404

ServiceQuotaExceededException

The request has exceeded the specified service quota.

HTTP Status Code: 402

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 429

UnauthorizedException

You do not have permission to perform this action.

HTTP Status Code: 401

ValidationException

The input fails to satisfy the constraints specified by the AWS service.

HTTP Status Code: 400