> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trainy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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



## OpenAPI

````yaml /pluto/api-reference/openapi.json post /api/runs/create
openapi: 3.0.0
info:
  title: mlop API
  version: 1.0.0
  description: API for mlop - ML experiment tracking platform
servers:
  - url: https://pluto-api.trainy.ai
    description: API Server
security:
  - bearerAuth: []
paths:
  /api/runs/create:
    post:
      tags:
        - Runs
      summary: Create a new run
      description: >-
        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).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                runName:
                  type: string
                  description: Name of the run
                  example: training-run-1
                projectName:
                  type: string
                  description: Name of the project
                  example: my-project
                externalId:
                  type: string
                  nullable: true
                  minLength: 1
                  description: >-
                    User-provided run ID for multi-node distributed training. If
                    provided and a run with this ID exists, the existing run is
                    returned.
                  example: my-ddp-run-2024
                tags:
                  type: array
                  nullable: true
                  items:
                    type: string
                  description: Tags for the run
                  example:
                    - experiment
                    - v1
                loggerSettings:
                  type: string
                  nullable: true
                  description: Logger settings as JSON string
                systemMetadata:
                  type: string
                  nullable: true
                  description: System metadata as JSON string
                config:
                  type: string
                  nullable: true
                  description: Run configuration as JSON string
                  example: '{"lr": 0.001}'
                createdAt:
                  type: number
                  nullable: true
                  description: Creation timestamp in milliseconds
                updatedAt:
                  type: number
                  nullable: true
                  description: Update timestamp in milliseconds
                forkRunId:
                  type: number
                  nullable: true
                  description: >-
                    ID of the run to fork from. Creates a child run that
                    inherits metrics up to forkStep.
                forkStep:
                  type: number
                  nullable: true
                  description: >-
                    Step at which to fork. Required when forkRunId is provided.
                    The child run inherits all metrics up to and including this
                    step.
                inheritConfig:
                  type: boolean
                  nullable: true
                  description: >-
                    Whether to inherit config from the parent run (default:
                    true). Only applies when forkRunId is provided.
                inheritTags:
                  type: boolean
                  nullable: true
                  description: >-
                    Whether to inherit tags from the parent run (default:
                    false). Only applies when forkRunId is provided.
              required:
                - runName
                - projectName
      responses:
        '200':
          description: Run created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRunResponse'
        '400':
          description: Organization is at limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateRunResponse:
      type: object
      properties:
        runId:
          type: number
          description: Numeric ID of the created run
        number:
          type: number
          nullable: true
          description: Sequential run number within the project (for display IDs)
        displayId:
          type: string
          nullable: true
          description: Human-readable display ID (e.g., 'MMP-1')
        projectName:
          type: string
          description: Name of the project
        organizationSlug:
          type: string
          description: Organization slug
        url:
          type: string
          description: URL to view the run
        resumed:
          type: boolean
          description: >-
            Whether an existing run was resumed (true) or a new run was created
            (false)
        forkedFromRunId:
          type: number
          nullable: true
          description: ID of the parent run this was forked from (null if not forked)
        forkStep:
          type: number
          nullable: true
          description: Step at which the fork occurred (null if not forked)
      required:
        - runId
        - number
        - displayId
        - projectName
        - organizationSlug
        - url
        - resumed
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key obtained from the mlop dashboard

````