NVIDIA Run:ai Distributed API
Distributed Training, is the ability to split the training of a model among multiple processors. It is often a necessity when multi-GPU training no longer applies; typically when you require more GPUs than exist on a single node. Each such split is a pod (see definition above). NVIDIA Run:ai spawns an additional launcher process that manages and coordinates the other worker pods. For more information, see [Distributed training](https://run-ai-docs.nvidia.com/saas/workloads-in-nvidia-run-ai/using-training/distributed-training/distributed-training-models).
NVIDIA Run:ai Distributed API is one of 62 APIs that NVIDIA Run:ai publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Distributed. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, and authentication docs.
This API exposes 5 operations across 4 paths, and defines 155 schemas. It is described by OpenAPI 3.2.0, at version latest.
Requests are made against a single base URL, https://app.run.ai.
5 operations
4 paths
155 schemas
1 DELETE1 GET3 POST
Metadata
The identity and technical contract details declared by the specification.
Authentication & Security 1
NVIDIA Run:ai Distributed API declares
1 security scheme
for authenticating requests.
It accepts HTTP bearer tokens (JWT) (bearerAuth).
By default, every request must be authenticated.
bearerAuth— Bearer authentication
Paths & Operations 5
Across 4 paths, the API surfaces 5 operations — 1 DELETE, 1 GET, 3 POST. Each is listed below with its method, path, parameters, and response codes.
Distributed 5
Distributed Training, is the ability to split the training of a model among multiple processors. It is often a necessity when multi-GPU training no longer applies; typically when…
POST
/api/v1/workloads/distributed
Create a distributed training
DELETE
/api/v1/workloads/distributed/{workloadId}
Delete a distributed training by id
GET
/api/v1/workloads/distributed/{workloadId}
Get distributed training's data. [Experimental]
POST
/api/v1/workloads/distributed/{workloadId}/suspend
Suspend a distributed training
POST
/api/v1/workloads/distributed/{workloadId}/resume
Resume a distributed training
Schemas 155
The contract defines 155 schemas that model the data the API accepts and returns. The most detailed are MasterSpec (32 properties), WorkloadMeta1 (11 properties), ExposedUrl (9 properties), EnvironmentVariable (8 properties). Each schema is shown below with its type and property counts.
EnvironmentVariableSecret
objectnull
Details of the secret and key use to populate the environment variable
2 properties
PriorityClass
stringnull
Specifies the priority class for the workload, which determines its scheduling behavior. Valid values are: very-low, low, medium-low, medium, medium-high, high…
DefaultMode
stringnull
File permission mode in octal string format. This value must be a 4-digit octal number, representing the default file mode when mounting a Secret or ConfigMap…
DistributedWorkload
CleanPodPolicy
stringnull
The policy describes how to deal with pods when the job is finished.
Tolerations
arraynull
Set of tolerations to apply to the workload.
SshAuthMountPath
stringnull
Specifies the directory where SSH keys are mounted. (applicable only for MPI)
GpuRequestType
stringnull
Sets the unit type for GPU resources requests. Stated in terms of portion or memory. Sets the unit type for other GPU request fields. If gpuDevicesRequest 1, o…
SecretItems1
arraynull
Set of secret volumes to use in the workload
ImagePullSecrets
arraynull
A list of references to Kubernetes secrets in the same namespace used for pulling container images.
MaxReplicas
integernull
the upper limit for the number of worker pods that can be set by the autoscaler. Cannot be smaller than MinReplicas. (applicable only for PyTorch)
Category
stringnull
Specify the workload category assigned to the workload. Categories are used to classify and monitor different types of workloads within the NVIDIA Run:ai platf…
LargeShmRequest
booleannull
A large /dev/shm device to mount into a container running the created workload. An shm is a shared file system mounted on RAM.
HostNetwork
booleannull
Whether to enable host networking. Default to false.
DataVolume
objectnull
2 properties
Image
stringnull
Docker image name. For more information, see [Images](https://kubernetes.io/docs/concepts/containers/images). The image name is mandatory for creating a worklo…
RelatedUrls
arraynull
Set of URLs that are related to the workload.
WorkingDir
stringnull
Container's working directory. If not specified, the container runtime default will be used. This may be configured in the container image.
StorageInstanceName
objectnull
1 property
EnvironmentVariable
objectnull
Details of an environment variable which is populated into the container.
8 properties
DepartmentId2
string
The id of the department.
SecretInstance2
objectnull
HttpResponse
object
2 properties
2 required
ProbeHandler
objectnull
The action taken to determine the health of the container. (mandatory)
1 property
PvcAddedAttrValues
array
an optional array of key-values pairs that are written as annotations on the created PVC. the allowed attributes are determined according to the storage class…
WorkloadDesiredPhase
string
The desired phase of the workload.
ComplianceIssuesV2
objectnull
1 property
EnvironmentVariablePodFieldReference
objectnull
Details of the field-reference and key use to populate the environment variable
1 property
Probe
objectnull
6 properties
Command
stringnull
A command to the server as the entry point of the container running the workload.
SlotsPerWorker
integernull
Specifies the number of slots per worker used in hostfile. Defaults to 1. (applicable only for MPI)
ImagePullSecret
objectnull
A reference to a secret in the same namespace used to pull container images.
3 properties
TolerationOperator
stringnull
A key's relationship to the value. Equal uses key and value. Exists is equivalent to wildcard for value, so that a workload can tolerate all taints of a partic…
CpuMemoryLimit
stringnull
Limitations on the CPU memory to allocate for this workload (1G, 20M, .etc). The system guarantees that this workload will not be able to consume more than thi…
EnvironmentVariableConfigMap
objectnull
Details of the configMap and key use to populate the environment variable
2 properties
MasterSpecSameAsWorker
booleannull
used for distributed workloads to indicate that the master spec should be the same as the worker spec. in this case, masterSpec should not be specified.
NodePools
arraynull
A prioritized list of node pools for the scheduler to run the workload on. The scheduler will always try to use the first node pool before moving to the next o…
CpuCoreRequest
numbernull
CPU units to allocate for the created workload (0.5, 1, .etc). The workload will receive at least this amount of CPU. Note that the workload will not be schedu…
ConfigMapItems
arraynull
Set of config map volumes to use in the workload
GitAuthenticationMethod
string
Specifies the authentication method to use when accessing the Git repository. This is required for private repositories - password - Authenticate using a usern…
PodAffinity
objectnull
Pod affinity scheduling rules (e.g. co-locate this workload in the same node, zone, etc. as some other workloads).
2 properties
PvcFieldsUpdatable
objectnull
1 property
HostPathMountPropagation
stringnull
Share this volumes mount with other containers. If set to HostToContainer, this volume mount will receive all subsequent mounts that are mounted to this volume…
Port
objectnull
A port for accessing the workload.
7 properties
AllowPrivilegeEscalation
booleannull
Allow the container running the workload and all launched processes to gain additional privileges after the workload starts. For more information consult the U…
BackoffLimitMaster
integernull
Specifies the number of retries before marking a workload as failed (not applicable to Inference workloads). The default value is 6.
PvcInstance
objectnull
DataVolumeItems
arraynull
Set of data volumes to use in the workload.
GpuMemoryRequest
stringnull
Required if and only if gpuRequestType is memory. States the GPU memory to allocate for the created workload, per GPU device. Note that the workload will not b…
NodeSelectorTerm
objectnull
A null or empty node selector term matches no objects. The requirements of them are ANDed.
1 property
S3Items
arraynull
Set of s3 buckets to use in the workload.
AutoDeletionTimeAfterPreemptionMaster
integernull
Specifies the duration after which a finished workload (completed or failed) will be automatically deleted. The default is 30 days. Log retention is managed se…
SubmissionErrorV2
CpuMemoryRequest
stringnull
The amount of CPU memory to allocate for this workload (1G, 20M, .etc). The workload will receive at least this amount of memory. Note that the workload will n…
SupplementalGroups
stringnull
Comma separated list of groups that the user running the container belongs to, in addition to the group indicated by runAsGid. Use only when the source uid/gid…
CreateHomeDir
booleannull
When set to true, creates a home directory for the container.
TerminationGracePeriodMaster
integernull
Duration in seconds the pod needs to terminate gracefully upon probe failure. The grace period is the duration in seconds after the processes running in the po…
PvcClaimSize
stringnull
Requested size for the PVC. Mandatory when existingPvc is false. Recommended sizes: TB/GB/MB/TIB/GIB/MIB
ExposedUrl
objectnull
A URL for accessing the workload.
9 properties
GitPassword
objectnull
3 properties
TerminationGracePeriod
integernull
Duration in seconds the pod needs to terminate gracefully upon probe failure. The grace period is the duration in seconds after the processes running in the po…
Nfs
objectnull
4 properties
PvcItems
arraynull
Set of pvc persistent volume claims to use in the workload.
RestartPolicy
stringnull
Specify the restart policy of the workload pods. Default is empty, which is determine by the framework default
EmptyDirInstance
objectnull
ProbeHandlerScheme
stringnull
Scheme to use for connecting to the host, defaults to HTTP.
PvcVolumeMode
stringnull
Default volume mode for the PVC. Choose between Filesystem (default) or Block.
ExtendedResource
objectnull
Quantity of an extended resource.
3 properties
EnvironmentVariableUserCredential
objectnull
Defines a reference to a user-created credential and a specific key within that credential whose value will populate the environment variable. User credentials…
2 properties
CpuCoreLimit
numbernull
Limitations on the number of CPUs consumed by the workload (0.5, 1, .etc). The system guarantees that this workload will not be able to consume more than this…
HostPathItems
arraynull
Set of host paths to use in the workload.
MpiLauncherCreationPolicy
stringnull
Define whether the MPI Launcher is created in parallel with the workers, or if its creation is postponed until all workers are in Ready state. This prevents fa…
S3AccessKey
objectnull
3 properties
TerminateAfterPreemption
booleannull
Indicates if the job should be terminated by the system after it has been preempted.
WorkloadCreationMeta
object
4 properties
3 required
GitCommon
objectnull
4 properties
ProjectId
string
The id of the project.
S3Common
objectnull
3 properties
Error
object
3 properties
2 required
SecretFieldsUpdatable
objectnull
2 properties
GitInstance
objectnull
Probes
objectnull
Probes are used to determine if the container is healthy and ready to accept traffic.
1 property
RunAsNonRoot
booleannull
Force the container to run as a non-root user.
Ports
arraynull
Set of container ports that the workload exposes.
DistributedSpec
object
The specifications of the training to be created.
3 properties
Labels
arraynull
Set of labels to populate into the container running the workload.
Label
objectnull
Label details to be populated into the container.
3 properties
NfsInstance
objectnull
PvcFieldsNonUpdatable
objectnull
6 properties
GitItems
arraynull
Set of git repositories to use in the workload.
GpuPortionRequest
numbernull
Required if and only if gpuRequestType is portion. States the portion of the GPU to allocate for the created workload, per GPU device, between 0 and 1. The def…
Annotations
arraynull
Set of annotations to populate into the container running the workload.
Args
stringnull
Arguments to the command that the container running the workload executes.
EnvironmentVariables
arraynull
Set of environment variables to populate into the container running the workload.
RunAsGid
integernull
The group id to run the entrypoint of the container which executes the workspace. Default to the value specified in the environment asset runAsGid field (optio…
NodeType3
stringnull
Nodes (machines), or a group of nodes on which the workload will run. To use this feature, your Administrator will need to label nodes. For more information, s…
DistributedSpecSpec
MasterSpec
objectnull
32 properties
Tty
booleannull
Whether this container should allocate a TTY for itself, also requires 'stdin' to be true.
ConfigMapInstance
objectnull
PolicyRuleEnum
stringnull
Indicates which validation rule (e.g., min, max, step, options, required, canEdit, canAdd) conflicted with policy restrictions, causing the asset or template t…
PortServiceType
stringnull
The service type of the port (mandatory).
SecretFieldsNonUpdatable
objectnull
1 property
Capability
string
ReadOnlyRootFileSystem
booleannull
If true, mounts the container's root filesystem as read-only.
PriorityClassMaster
stringnull
Specifies the priority class for the workload, which determines its scheduling behavior. Valid values are: very-low, low, medium-low, medium, medium-high, high…
ExtendedResources
arraynull
Extended resources and their quantity.
WorkloadId2
string
A unique ID of the workload.
NumWorkers
integernull
the number of workers that will be allocated for running the workload.
Stdin
booleannull
Whether this container should allocate a buffer for stdin in the container runtime. If this is not set, reads from stdin in the container will always result in…
PodAffinityType
stringnull
The affinity type, required or preferred. (mandatory)
DistributedFramework
stringnull
The distributed training framework used in the workload.
UidGidSource
stringnull
Indicate the way to determine the user and group ids of the container. The options are a. fromTheImage - user and group ids are determined by the docker image…
GpuDevicesRequest
integernull
Requested number of GPU devices. Currently if more than one device is requested, it is not possible to provide values for gpuMemory or gpuPortion.
MatchExpression
objectnull
A selector that contains values, a key, and an operator that relates the key and values.
3 properties
2 required
NfsItems
arraynull
Set of nfs volumes to use in the workload.
GitSecretRef
objectnull
4 properties
GpuPortionLimit
numbernull
Limitations on the portion consumed by the workload, per GPU device. The system guarantees The gpuPotionLimit must be no less than the gpuPortionRequest.
Annotation
objectnull
Annotation details to be populated into the container.
3 properties
ImagePullPolicy
stringnull
Image pull policy. Defaults to Always if :latest tag is specified, otherwise it is IfNotPresent.
Toleration
objectnull
Toleration details.
7 properties
Secret5
PvcAddedAttrValue
object
2 properties
1 required
EmptyDirItems
arraynull
A list of emptyDir volumes to mount in the workload.
Preemptibility
stringnull
Specifies whether the workload can be preempted by higher-priority workloads. Valid values are preemptible and non-preemptible. If explicitly set, this value t…
Capabilities
arraynull
Add POSIX capabilities to running containers. Defaults to the default set of capabilities granted by the container runtime.
S3Instance
objectnull
RelatedUrl
objectnull
A URL that is related to the workload. For example, a URL to an external server providing statistics or logging about the workload.
4 properties
NodeAffinityRequired
objectnull
If the affinity requirements specified by this field are not met at scheduling time, the pod will not be scheduled onto the node. If the affinity requirements…
1 property
RunAsUid
integernull
The user id to run the entrypoint of the container which executes the workspace. Default to the value specified in the environment asset runAsUid field (option…
ExcludeField
objectnull
1 property
AuthorizationType
stringnull
Specifies who can access the connection URL: - authenticatedUsers: Any authenticated user or service account can access the URL; the authorizedUsers and author…
WorkloadMeta1
object
11 properties
8 required
Pvc
ClusterId
string
The id of the cluster.
ExposedUrls
arraynull
Set of container ports that the workload exposes via URLs.
EmptyDir
objectnull
3 properties
ClaimInfo
objectnull
Claim information for the newly created PVC. The information should not be provided when attempting to use existing PVC.
5 properties
HostPath
objectnull
4 properties
SubmitWithTemplateId
object
1 property
TolerationEffect
stringnull
The taint effect to match. (mandatory)
AutoDeletionTimeAfterPreemption
integernull
Specifies the duration after which a finished workload (completed or failed) will be automatically deleted. The default is 30 days. Log retention is managed se…
Phase
string
PvcAccessModes
objectnull
Default access mode(s) applied to newly created PVCs unless explicitly overridden.
3 properties
ConfigMap
objectnull
4 properties
MinReplicas
integernull
the lower limit for the number of worker pods to which the training job can scale down. (applicable only for PyTorch)
BackoffLimit
integernull
Specifies the number of retries before marking a workload as failed (not applicable to Inference workloads). The default value is 6.
SeccompProfileType
stringnull
Indicates which kind of seccomp profile will be applied to the container. The options are a. RuntimeDefault - the container runtime default profile should be u…
DistributedCreationRequest
MatchExpressionOperator
string
Represents a key's relationship to a set of values (mandatory).
HostIpc
booleannull
Whether to enable host IPC. Defaults to false.
WorkloadName
string
The name of the workload.
DataVolumeInstance
objectnull
GpuMemoryLimit
stringnull
Limitation on the memory consumed by the workload, per GPU device. The system guarantees The gpuMemoryLimit must be no less than gpuMemoryRequest.
HostPathInstance
objectnull
Specification
The full machine-readable OpenAPI contract behind this narrative.
Source
More from NVIDIA Run:ai 12
Other APIs NVIDIA Run:ai publishes across the network.
NVIDIA Run:ai Access Keys API
NVIDIA Run:ai Access rules API
NVIDIA Run:ai Administrator Command Line Interface API
NVIDIA Run:ai AI Applications API
NVIDIA Run:ai Applications API
NVIDIA Run:ai Clusters API
NVIDIA Run:ai Compute API
NVIDIA Run:ai ConfigMap API
NVIDIA Run:ai Credentials API
NVIDIA Run:ai Departments API
NVIDIA Run:ai Distributed Inferences API
NVIDIA Run:ai Environment API
#Distributed
Where this information came from
This is an independent, third-party profile of NVIDIA Run:ai Distributed API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com
·
Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and
you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.