---
title: "Create a new run"
method: POST
path: "/api/runs/create"
tags: ["Runs"]
---

# Create a new run

`POST /api/runs/create`

## Request

- Base URL: `https://pluto-api.trainy.ai`
- URL: `https://pluto-api.trainy.ai/api/runs/create`
- Auth: HTTP bearer

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).

## Request body

- CreateRunRequest
  - `runName` string, required: Name of the run
  - `projectName` string, required: Name of the project
  - `externalId` string, nullable: User-provided run ID for multi-node distributed training. If provided and a run with this ID exists, the existing run is returned.
  - `tags` string[], nullable: Tags for the run (max 50)
  - `loggerSettings` string, nullable: Logger settings as JSON string
  - `systemMetadata` string, nullable: System metadata as JSON string
  - `config` string, nullable: Run configuration as JSON string
  - `createdAt` integer, nullable: Creation timestamp in epoch milliseconds (backfill/migration)
  - `updatedAt` integer, nullable: Update timestamp in epoch milliseconds (backfill/migration)
  - `forkRunId` number, nullable: ID of the run to fork from. Creates a child run that inherits metrics up to forkStep.
  - `forkStep` number, nullable: Step at which to fork. Required when forkRunId is provided. The child run inherits all metrics up to and including this step.
  - `inheritConfig` boolean, nullable: Whether to inherit config from the parent run (default: true). Only applies when forkRunId is provided.
  - `inheritTags` boolean, nullable: Whether to inherit tags from the parent run (default: false). Only applies when forkRunId is provided.

## Response `200`

Run created successfully

- CreateRunResponse
  - `runId` number, required: Numeric ID of the created run
  - `number` number, nullable, required: Sequential run number within the project (for display IDs)
  - `displayId` string, nullable, 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, nullable: ID of the parent run this was forked from (null if not forked)
  - `forkStep` number, nullable: Step at which the fork occurred (null if not forked)

## Other responses

- `400`: Organization is at limit
- `401`: Unauthorized
- `500`: Internal server error

---

[API](https://skmtc.dev/trainy/apis/mlop-api.md) - [All operations](https://skmtc.dev/trainy/apis/mlop-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trainy/apis/mlop-api/revisions/5d2c0b0baecb?raw)