# Work with ML training jobs with Viam's ML training API

The ML training API allows you to get information about and cancel ML training jobs running on Viam.

The ML training client API supports the following methods:

| Method Name | Description |
| --- | --- |
| [`SubmitTrainingJob`](https://docs.viam.com/reference/apis/ml-training-client/#submittrainingjob) | Submit a training job. |
| [`SubmitCustomTrainingJob`](https://docs.viam.com/reference/apis/ml-training-client/#submitcustomtrainingjob) | Submit a training job from a custom training script. |
| [`GetTrainingJob`](https://docs.viam.com/reference/apis/ml-training-client/#gettrainingjob) | Get training job metadata. |
| [`ListTrainingJobs`](https://docs.viam.com/reference/apis/ml-training-client/#listtrainingjobs) | Get training job metadata for all jobs within an organization. |
| [`CancelTrainingJob`](https://docs.viam.com/reference/apis/ml-training-client/#canceltrainingjob) | Cancel the specified training job. |
| [`DeleteCompletedTrainingJob`](https://docs.viam.com/reference/apis/ml-training-client/#deletecompletedtrainingjob) | Delete a completed training job from the database, whether the job succeeded or failed. |

## Establish a connection

To use the ML training client API, you need to instantiate a `ViamClient` and then instantiate an `MLTrainingClient`.

You need an API key and API key ID with [Org owner permissions](https://docs.viam.com/organization/rbac/#organization-settings-and-roles) to use the MLTraining client API. To get an API key (and corresponding ID), use the [web UI](https://docs.viam.com/organization/api-keys/#create-an-api-key) to the [Viam CLI](https://docs.viam.com/cli/).

- [From a client application](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-2-0)
- [From within a Module](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-2-1)

- [Python](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-1-0)
- [Go](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-1-1)
- [TypeScript](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-1-2)

```python

```

Copy

```go

```

Copy

```ts

```

Copy

Once you have instantiated an `MLTrainingClient`, you can run the following [API methods](https://docs.viam.com/reference/apis/ml-training-client/#api) against the `MLTrainingClient` object (named `ml_training_client` in the examples).

## API

### SubmitTrainingJob

Submit a training job.

- [Python](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-3-0)
- [Go](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-3-1)
- [TypeScript](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-3-2)

**Parameters:**

- `org_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The ID of the organization to submit the training job to. To retrieve this, expand your organization’s dropdown in the top right corner on [Viam](https://app.viam.com/), select **Settings**, and copy **Organization ID**.
- `dataset_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The ID of the dataset to train the ML model on. To retrieve this, navigate to your [dataset’s page](https://app.viam.com/data/datasets), click **…** in the left-hand menu, and click **Copy dataset ID**.
- `model_name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the model name.
- `model_version` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The version of the ML model you’re training. This string must be unique from any previous versions you’ve set.
- `model_type` (viam.proto.app.mltraining.ModelType.ValueType) (required): The type of the ML model. Options: `ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_MULTI_LABEL_CLASSIFICATION`, `ModelType.MODEL_TYPE_OBJECT_DETECTION`.
- `tags` (List[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)]) (required): the labels to train the model on.

**Returns:**

- ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): : the ID of the training job.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.submit_training_job).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `args` [(SubmitTrainingJobArgs)](https://pkg.go.dev/go.viam.com/rdk/app#SubmitTrainingJobArgs)
- `modelType` [(ModelType)](https://pkg.go.dev/go.viam.com/rdk/app#ModelType)
- `tags` [([]string)](https://pkg.go.dev/builtin#string)

**Returns:**

- [(string)](https://pkg.go.dev/builtin#string)
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/app#MLTrainingClient.SubmitTrainingJob).

**Parameters:**

- `organizationId` (string) (required): The organization ID.
- `datasetId` (string) (required): The dataset ID.
- `modelName` (string) (required): The model name.
- `modelVersion` (string) (required): The model version.
- `modelType` ( [ModelType](https://ts.viam.dev/enums/ModelType.html)) (required): The model type.
- `tags` (string) (required): The tags.

**Returns:**

- (Promise)

**Example:**

```ts

```

Copy

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/interfaces/MlTrainingClient.html#submittrainingjob).

### SubmitCustomTrainingJob

Submit a training job from a custom training script. Follow the guide to [Train a Model with a Custom Python Training Script](https://docs.viam.com/train/custom-training-scripts/).

- [Python](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-4-0)
- [Go](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-4-1)
- [TypeScript](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-4-2)

**Parameters:**

- `org_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the org to submit the training job to.
- `dataset_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the dataset to train the model on.
- `registry_item_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the training script from the registry.
- `registry_item_version` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the version of the training script from the registry.
- `model_name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the model name.
- `model_version` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the model version.

**Returns:**

- ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)): the ID of the training job.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.submit_custom_training_job).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `args` [(SubmitTrainingJobArgs)](https://pkg.go.dev/go.viam.com/rdk/app#SubmitTrainingJobArgs)
- `registryItemID`
- `registryItemVersion` [(string)](https://pkg.go.dev/builtin#string)
- `arguments` [(map[string]string)](https://pkg.go.dev/builtin#string)

**Returns:**

- [(string)](https://pkg.go.dev/builtin#string)
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/app#MLTrainingClient.SubmitCustomTrainingJob).

**Parameters:**

- `organizationId` (string) (required): The organization ID.
- `datasetId` (string) (required): The dataset ID.
- `registryItemId` (string) (required): The registry item ID.
- `registryItemVersion` (string) (required): The registry item version.
- `modelName` (string) (required): The model name.
- `modelVersion` (string) (required): The model version.

**Returns:**

- (Promise)

**Example:**

```ts

```

Copy

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/interfaces/MlTrainingClient.html#submitcustomtrainingjob).

### GetTrainingJob

Get training job metadata.

- [Python](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-5-0)
- [Go](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-5-1)
- [TypeScript](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-5-2)

**Parameters:**

- `id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the requested training job.

**Returns:**

- ( [viam.proto.app.mltraining.TrainingJobMetadata](https://python.viam.dev/autoapi/viam/proto/app/mltraining/index.html#viam.proto.app.mltraining.TrainingJobMetadata)): the training job data.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.get_training_job).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `id` [(string)](https://pkg.go.dev/builtin#string)

**Returns:**

- [(*TrainingJobMetadata)](https://pkg.go.dev/go.viam.com/rdk/app#TrainingJobMetadata)
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/app#MLTrainingClient.GetTrainingJob).

**Parameters:**

- `id` (string) (required): The training job ID.

**Returns:**

- (Promise<undefined | [TrainingJobMetadata](https://ts.viam.dev/classes/mlTrainingApi.TrainingJobMetadata.html) >)

**Example:**

```ts

```

Copy

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/interfaces/MlTrainingClient.html#gettrainingjob).

### ListTrainingJobs

Get training job metadata for all jobs within an organization.

- [Python](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-6-0)
- [Go](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-6-1)
- [TypeScript](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-6-2)

**Parameters:**

- `org_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the org to request training job data from.
- `training_status` ( [viam.proto.app.mltraining.TrainingStatus.ValueType](https://python.viam.dev/autoapi/viam/gen/app/mltraining/v1/ml_training_pb2/index.html#viam.gen.app.mltraining.v1.ml_training_pb2.TrainingStatus)) (optional): the status to filter the training jobs list by. If unspecified, all training jobs will be returned.

**Returns:**

- ( [List[viam.proto.app.mltraining.TrainingJobMetadata]](https://python.viam.dev/autoapi/viam/proto/app/mltraining/index.html#viam.proto.app.mltraining.TrainingJobMetadata)): the list of training job data.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.list_training_jobs).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `organizationID` [(string)](https://pkg.go.dev/builtin#string)
- `status` [(TrainingStatus)](https://pkg.go.dev/go.viam.com/rdk/app#TrainingStatus)

**Returns:**

- [([]*TrainingJobMetadata)](https://pkg.go.dev/go.viam.com/rdk/app#TrainingJobMetadata)
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/app#MLTrainingClient.ListTrainingJobs).

**Parameters:**

- `organizationId` (string) (required): The organization ID.
- `status` ( [TrainingStatus](https://ts.viam.dev/enums/TrainingStatus.html)) (required): The training job status.

**Returns:**

- (Promise< [TrainingJobMetadata](https://ts.viam.dev/classes/mlTrainingApi.TrainingJobMetadata.html)[]> )

**Example:**

```ts

```

Copy

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/interfaces/MlTrainingClient.html#listtrainingjobs).

### CancelTrainingJob

Cancel the specified training job.

- [Python](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-7-0)
- [Go](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-7-1)
- [TypeScript](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-7-2)

**Parameters:**

- `id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): ID of the training job you wish to get metadata from. Retrieve this value with [`ListTrainingJobs()`](https://docs.viam.com/reference/apis/ml-training-client/#listtrainingjobs).

**Returns:**

- None.

**Raises:**

- (GRPCError): if no training job exists with the given ID.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.cancel_training_job).

**Parameters:**

**Returns:**

- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/app#MLTrainingClient.CancelTrainingJob).

**Parameters:**

- `id` (string) (required): The training job ID.

**Returns:**

- (Promise)

**Example:**

```ts

```

Copy

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/interfaces/MlTrainingClient.html#canceltrainingjob).

### DeleteCompletedTrainingJob

Delete a completed training job from the database, whether the job succeeded or failed.

- [Python](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-8-0)
- [Go](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-8-1)
- [TypeScript](https://docs.viam.com/reference/apis/ml-training-client/#tabset-referenceapisml-training-client-8-2)

**Parameters:**

- `id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the training job to delete.

**Returns:**

- None.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/ml_training_client/index.html#viam.app.ml_training_client.MLTrainingClient.delete_completed_training_job).

**Parameters:**

**Returns:**

- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/app#MLTrainingClient.DeleteCompletedTrainingJob).

**Parameters:**

- `id` (string) (required): The training job ID.

**Returns:**

- (Promise)

**Example:**

```ts

```

Copy

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/interfaces/MlTrainingClient.html#deletecompletedtrainingjob).