Create a new run

Creates a new run in the specified project. If the project doesn’t exist, it will be created. If externalId is provided and a run with that ID already exists, the existing run is returned (Neptune-style resume for multi-node distributed training).

POST /api/runs/create

Create a new run

cURL

curl --request POST \
  --url https://pluto-api.trainy.ai/api/runs/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "runName": "training-run-1",
  "projectName": "my-project",
  "externalId": "my-ddp-run-2024",
  "tags": [
    "experiment",
    "v1"
  ],
  "loggerSettings": "<string>",
  "systemMetadata": "<string>",
  "config": "{\"lr\": 0.001}",
  "createdAt": 123,
  "updatedAt": 123,
  "forkRunId": 123,
  "forkStep": 123,
  "inheritConfig": true,
  "inheritTags": true
}
'

200

{
  "runId": 123,
  "number": 123,
  "displayId": "<string>",
  "projectName": "<string>",
  "organizationSlug": "<string>",
  "url": "<string>",
  "resumed": true,
  "forkedFromRunId": 123,
  "forkStep": 123
}

Authorizations

Authorization · string · header · required

API key obtained from the mlop dashboard

Body

application/json

runName · string · required

Name of the run

Example:

"training-run-1"

projectName · string · required

Name of the project

Example:

"my-project"

externalId · string | null

User-provided run ID for multi-node distributed training. If provided and a run with this ID exists, the existing run is returned.

Minimum string length: 1

Example:

"my-ddp-run-2024"

tags · string[] | null

Tags for the run

Example:

["experiment", "v1"]

loggerSettings · string | null

Logger settings as JSON string

systemMetadata · string | null

System metadata as JSON string

config · string | null

Run configuration as JSON string

Example:

"{\"lr\": 0.001}"

createdAt · number | null

Creation timestamp in milliseconds

updatedAt · number | null

Update timestamp in milliseconds

forkRunId · number | null

ID of the run to fork from. Creates a child run that inherits metrics up to forkStep.

forkStep · number | null

Step at which to fork. Required when forkRunId is provided. The child run inherits all metrics up to and including this step.

inheritConfig · boolean | null

Whether to inherit config from the parent run (default: true). Only applies when forkRunId is provided.

inheritTags · boolean | null

Whether to inherit tags from the parent run (default: false). Only applies when forkRunId is provided.

Response

200

application/json

Run created successfully

runId · number · required

Numeric ID of the created run

number · number | null · required

Sequential run number within the project (for display IDs)

displayId · string | null · required

Human-readable display ID (e.g., 'MMP-1')

projectName · string · required

Name of the project

organizationSlug · string · required

Organization slug

url · string · required

URL to view the run

resumed · boolean · required

Whether an existing run was resumed (true) or a new run was created (false)

forkedFromRunId · number | null

ID of the parent run this was forked from (null if not forked)

forkStep · number | null

Step at which the fork occurred (null if not forked)