Sign in
Jobs

Trigger a Run from a Job

Changed on
post/api/v1/jobs/{name}/runs

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/jobs/{name}/runs
  • Auth: none declared

Path parameters

namestring required

Headers

X-Axisml-Tenantstring

Active tenant for the request (fallback for the axisml.tenant cookie).

Request body

annotationsStringMap
displayNamestring

Display name for the triggered run.

labelsStringMap
poolNamestring

Override resource pool for this run.

resourcesResourceMap

Kubernetes-style resource quantity map (e.g., {"cpu": "100", "memory": "1Ti", "nvidia.com/gpu": "8"}).

unitNamestring

Override resource unit (shape) for this run.

Example request

{
  "displayName": "ResNet-50 Training #8",
  "poolName": "gpu-a100",
  "roles": [
    {
      "args": [
        "--epochs",
        "120"
      ],
      "name": "worker"
    }
  ],
  "unitName": "a100-2x"
}

Response

Run triggered.

annotationsStringMap
computeNamespacestring

Underlying compute (Kubernetes) namespace executing the run.

createdAtstring date-time required

Time the run was created.

descriptionstring

Free-text run description.

displayNamestring

Human-readable run label.

finishedAtstring date-time nullable

Time the run reached a terminal phase.

idstring uuid

Stable run identifier.

jobNamestring

Name of the Job definition that produced this run.

messagestring

Human-readable status detail for the current phase.

namestring required

Run name (<job>-<n>).

namespacestring required

Platform tenant namespace the run belongs to.

ownerstring required

Username of the run owner.

ownerIdstring uuid

User ID of the run owner.

phase'Queued' | 'Creating' | 'Pending' | 'Running' | 'Succeeded' | 'Failed' | 'Canceling' | 'Cancelled' | 'Deleting' | 'Deleted'

Run (compute MLRun) phase. The active (non-terminal) phases — Creating / Pending / Running / Canceling — block Job-definition deletion.

poolNamestring

Resource pool the run is scheduled onto.

queueReasonstring

Stable reason explaining why a Run remains Queued.

resourcesResourceMap

Kubernetes-style resource quantity map (e.g., {"cpu": "100", "memory": "1Ti", "nvidia.com/gpu": "8"}).

runNumberinteger

Monotonic per-job run sequence number.

scheduledAtstring date-time nullable

Time the runtime accepted the run and it entered Pending.

startedAtstring date-time nullable

Time the run started executing.

tenantDisplayNamestring

Human-readable tenant name.

tenantNamestring required

Tenant identifier owning the run.

unitNamestring

Resource unit (shape) within the pool.

updatedAtstring date-time required

Time the run was last updated.

Example response

{
  "backend": {
    "engine": "pytorchjob",
    "name": "native"
  },
  "computeNamespace": "axisml-team-vision",
  "createdAt": "2026-06-28T09:00:00Z",
  "description": "Distributed ResNet-50 training run on ImageNet.",
  "displayName": "ResNet-50 Training #7",
  "id": "b7d9e3f1-1a2b-3c4d-5e6f-708192a3b4c5",
  "jobName": "resnet-train",
  "message": "All worker replicas ready.",
  "name": "resnet-train-7",
  "namespace": "team-vision",
  "owner": "li.wei",
  "ownerId": "3a2b1c0d-4e5f-6789-abcd-ef0123456789",
  "phase": "Running",
  "poolName": "gpu-a100",
  "resources": {
    "cpu": "32",
    "memory": "256Gi",
    "nvidia.com/gpu": "8"
  },
  "roles": [
    {
      "activeReplicas": 4,
      "failedReplicas": 0,
      "name": "worker",
      "readyReplicas": 4,
      "replicas": 4,
      "restartPolicy": "OnFailure",
      "succeededReplicas": 0,
      "template": {
        "args": [
          "--epochs",
          "90",
          "--batch-size",
          "256"
        ],
        "command": [
          "python",
          "train.py"
        ],
        "env": [
          {
            "name": "NCCL_DEBUG",
            "value": "INFO"
          }
        ],
        "envFrom": [
          {
            "configMapRef": {
              "name": "resnet-training-config"
            }
          }
        ],
        "image": "registry.axisml.io/training/resnet:1.4.0",
        "ports": [
          {
            "containerPort": 8080,
            "name": "http",
            "protocol": "TCP"
          }
        ],
        "resources": {
          "cpu": "8",
          "memory": "64Gi",
          "nvidia.com/gpu": "2"
        },
        "volumeMounts": [
          {
            "mountPath": "/data",
            "name": "data"
          },
          {
            "mountPath": "/etc/axisml",
            "name": "config",
            "readOnly": true
          }
        ],
        "volumes": [
          {
            "name": "data",
            "persistentVolumeClaim": {
              "claimName": "resnet-imagenet"
            }
          },
          {
            "configMap": {
              "name": "resnet-training-config"
            },
            "name": "config"
          }
        ]
      }
    }
  ],
  "runNumber": 7,
  "runPolicy": {
    "activeDeadlineSeconds": 86400,
    "backoffLimit": 2,
    "progressDeadlineSeconds": 600,
    "ttlSecondsAfterFinished": 3600
  },
  "scheduledAt": "2026-06-28T09:00:00Z",
  "spec": {
    "backend": {
      "engine": "pytorchjob",
      "name": "native"
    },
    "configMaps": [
      {
        "data": {
          "trainer.yaml": "epochs: 90\nbatchSize: 256\n"
        },
        "name": "resnet-training-config"
      }
    ],
    "roles": [
      {
        "name": "worker",
        "replicas": 4,
        "restartPolicy": "OnFailure",
        "template": {
          "args": [
            "--epochs",
            "90",
            "--batch-size",
            "256"
          ],
          "command": [
            "python",
            "train.py"
          ],
          "env": [
            {
              "name": "NCCL_DEBUG",
              "value": "INFO"
            }
          ],
          "envFrom": [
            {
              "configMapRef": {
                "name": "resnet-training-config"
              }
            }
          ],
          "image": "registry.axisml.io/training/resnet:1.4.0",
          "ports": [
            {
              "containerPort": 8080,
              "name": "http",
              "protocol": "TCP"
            }
          ],
          "resources": {
            "cpu": "8",
            "memory": "64Gi",
            "nvidia.com/gpu": "2"
          },
          "volumeMounts": [
            {
              "mountPath": "/data",
              "name": "data"
            },
            {
              "mountPath": "/etc/axisml",
              "name": "config",
              "readOnly": true
            }
          ],
          "volumes": [
            {
              "name": "data",
              "persistentVolumeClaim": {
                "claimName": "resnet-imagenet"
              }
            },
            {
              "configMap": {
                "name": "resnet-training-config"
              },
              "name": "config"
            }
          ]
        }
      }
    ],
    "runPolicy": {
      "activeDeadlineSeconds": 86400,
      "backoffLimit": 2,
      "progressDeadlineSeconds": 600,
      "ttlSecondsAfterFinished": 3600
    },
    "scheduling": {
      "minMember": 4,
      "priorityClass": "high-priority",
      "quota": "axisml-team-vision-gpu-a100"
    }
  },
  "startedAt": "2026-06-28T09:00:00Z",
  "tenantDisplayName": "Vision Team",
  "tenantName": "team-vision",
  "unitName": "a100-2x",
  "updatedAt": "2026-06-28T09:30:00Z"
}

Changes

  • 2460d3212e9bRevision changes
    • warning

      added the new Queued enum value to the //// response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • d00d802bd072Revision changes
    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property //////////// to the response with the status