PRprimeintellect
training

Create Dedicated Run

Changed on

Dispatch a dedicated full-FT prime-rl run on a registered PrimeCluster.

Access is gated by ClusterAllocation - the picker in training_service.create_dedicated_run rejects callers whose team/user has no matching allocation on a live PrimeCluster. When team_id is set the caller must additionally be a member of that team (mirrors the LoRA/shared dispatch path).

Admission checks (runtime pins, hub env ids, HF repo names, per-run GPU cap) run sync so bad configs return 400 immediately. Local clients supply normalized configs; legacy clients use the validator schema. Cluster-side probes (GPU capacity, model cache) and the helm install run async in a Cloud Task; callers poll GET /api/v1/rft/runs/{run_id} for status transitions PENDING -> CREATING -> RUNNING (or FAILED with errorMessage on a cluster-side rejection).

post/api/v1/training/runs

Request

  • Base URL
    https://api.primeintellect.ai
  • Auth
    HTTP bearer

Request body

wandbApiKeystring nullable

W&B key. On the PENDING fast-path it's materialised straight into the run's k8s Secret. On the QUEUED path it's stashed AES-encrypted on the RFTRun row so the drainer can rebuild the same Secret at promotion time without re-prompting.

hfTokenstring nullable

HF token for gated/private model downloads. Same storage rules as wandbApiKey above.

secretsobject nullable

Arbitrary env-var secrets projected into trainer / inference / orchestrator / env-server pods (parity with the LoRA path). Keys must be uppercase POSIX env-var names (e.g. 'OPENAI_API_KEY'); WANDB_API_KEY / HF_TOKEN / PRIME_API_KEY are reserved — use the dedicated fields for those. Materialised into the per-run k8s Secret. Held encrypted on the RFTRun row only for the sync -> dispatch-task hop, then cleared once the run deploys (or on stop / delete / rollback); never returned by any read endpoint.

configobject required

Full prime-rl-style TOML, parsed to a dict. Same shape as prime-rl/examples/*/rl.toml; the platform splits it into trainer / orchestrator / inference subconfigs and bakes each into the corresponding pod's startup command.

mode'rl' | 'sft'

Which prime-rl schema the config blob follows. 'rl' (default) is the RL mega-TOML (trainer + orchestrator + inference). 'sft' is the SFT mega-TOML (top-level model/data/optim blocks, trainer-only deployment): the validator validates it against SFTConfig and renders a trainer-only Helm release (no orchestrator, inference, or env-server pods). The caller declares the mode; the backend never sniffs the config shape.

imageTagstring nullable

prime-rl container image tag on ghcr.io/primeintellect-ai/prime-rl. Omit to use the deployment default: the operator-configured RL_FFT_DEFAULT_IMAGE_TAG when set, otherwise the validator's pinned build for RL runs and main for SFT runs. An explicit value, including main, is always used as-is.

sourceRefstring nullable

prime-rl git ref (branch, tag, or sha in the canonical PrimeIntellect-ai/prime-rl repo) the pods check out over the image's baked source at start, so a branch can be tested without building an image. The validator resolves it to a commit and validates the config against that commit's schema; the resolved sha is pinned on the run. Not generally available: only team runs (teamId) may send it, the team needs sourceRef access granted (contact support), and the backend needs RL_SOURCE_REF_ENABLED.

namestring nullable

Optional human-readable run name

teamIdstring nullable

Owning team (defaults to caller's user)

volumestring nullable

Name of a volume in the caller's team (or personal) namespace. The run writes its outputs to runs/<runId>/ on it instead of to a per-run PVC.

resumeFromstring nullable

Id of a PAUSED run to resume: this run attaches its volume and starts from its checkpoint, on any cluster. Send the same config; volume may be omitted.

gpuTypestring nullable

Optional GPU type constraint (e.g. 'H200_141GB', 'B200_180GB'). When set, dispatch is restricted to PrimeClusters whose gpuType matches. When omitted, the picker chooses the oldest eligible cluster with no type preference. On the on-demand path the type determines the price, so when it is omitted the cheapest purchasable type is chosen and echoed back on the response.

normalizedConfigobject nullable

Response

Successful Response

runIdstring required
jobIdstring required
tokenValuestring required

PRIME_API_KEY for this run. Returned once — the platform stores only the token id.

onDemandboolean

True when this run landed on billed shared capacity rather than a cluster the caller holds an allocation on. Derived at dispatch, not requested.

gpuTypestring nullable

GPU type the run was placed on.

pricePerGpuHournumber nullable

USD per GPU-hour this run will be charged, discount applied and frozen for its lifetime. NULL on reserved capacity, which bills nothing per-hour. Echoed so a caller who named no gpuType sees the rate now rather than at invoice time.

estimatedCostPerHournumber nullable

price_per_gpu_hour multiplied by the run's GPU count.

isBetaboolean

True when this run used on-demand capacity, which is in beta. False on the reserved path, which is GA.

Changes