Run a job
Run one command on its own fresh GPU machine, or a group of them with count or params. Runcrate tries the GPUs in gpu_type in order and, when none has capacity, keeps the job queued and tries again (1, 2, 4, then every 5 minutes) for up to capacity_wait_minutes. It runs the command with bash in /workspace, streams its output to GET /jobs/{id}/logs, and stops the machine as soon as the command exits, hits max_runtime_minutes or is cancelled. A failed attempt is retried on a new machine under max_retries. Files written under /workspace are saved back to the volume (storage_id) when each machine stops. The machine also shows in GET /instances while it runs. With capacity_wait_minutes: 0, a job that could not be launched answers the error with details.job_id, and that job is failed. Send an Idempotency-Key header to retry safely.
Authorizations
Use a Runcrate API key with the rc_live_* prefix as the bearer token. Create one at https://www.runcrate.ai/dashboard/api-keys.
Headers
Unique per environment for 24 hours. Sending the same request again answers the original job (or group) with 200 and Idempotent-Replayed: true instead of starting another; the same key with a different request is a 409 with details.reason: idempotency_conflict.
255Body
Shell command, run with bash in /workspace. At most 65536 bytes. It must also fit in the machine's launch script: about 5 KB of ordinary shell. Put a longer script in a file on a volume or in the image and run that.
1GPU model (e.g. A4000, H100), as listed by GET /instances/types, or a list to try in order, e.g. ["H100", "A100-80GB:2"]. :N sets that entry's GPU count; entries without one use gpu_count.
Longest each attempt's command may run, counted from when it starts, up to 7 days. Required: a job never runs unbounded.
1 <= x <= 100801 <= x <= 8OS template id from GET /templates.
Container image to run the command in. /workspace is mounted and the image is pulled before the max runtime starts. The GPUs are passed into the container only on machines with the NVIDIA container runtime; otherwise the job log says so and the command runs without GPUs. The image needs bash or sh.
Environment variables for the command, as { "KEY": "value" }, added to the environment's secrets (a name set in both takes this value). Keys match ^[A-Za-z_][A-Za-z0-9_]*$ and don't start with RUNCRATE_; at most 200 keys, values up to 32 KB, 64 KB in total with the secrets. Values are stored only encrypted and never returned.
Volume to mount at /workspace. Must be in the same workspace and environment and not attached to another machine.
Defaults to job-<first 8 chars of id>.
63Only run in this region, matched as for instances. Defaults to any region.
How long to wait for capacity on any of the GPUs before the job fails. The job stays queued with queue_reason: no_capacity meanwhile. 0 fails at once.
0 <= x <= 1440Run the command again on a new machine at most this many times when an attempt fails. A machine failure is always retried; a failing command only under retry_on or retry_exit_codes.
0 <= x <= 10What is retried. machine_failure is on whenever max_retries is above 0.
machine_failure, nonzero_exit Retry only these exit codes. Takes precedence over nonzero_exit.
321 <= x <= 255Run this many copies as a group. Each sees RUNCRATE_JOB_INDEX and RUNCRATE_JOB_COUNT.
1 <= x <= 100One env object per job of a group, merged over env. Instead of count.
1 - 100 elementsWith count or params: how many of the group run at once. Defaults to all.
1 <= x <= 100At most 20. Keys match ^[a-z0-9_.:-]{1,40}$.
https URL that gets the job's events, signed like the workspace's webhooks (or with a webhook_secret returned once when the workspace has no webhook endpoint), delivered and retried the same way.
started, finished Same as the Idempotency-Key header, for clients that cannot set headers.
255Code put in /workspace/code before the command starts; the command runs there.
Sign in to the image's registry before the pull, with the values of these two env variables or secrets.
Run the image without GPUs when the machine cannot pass them into a container, instead of failing.
Response
A replay of an earlier request with the same Idempotency-Key: the job (or group) it created, as it is now. The Idempotent-Replayed: true header is set.
One command run on its own fresh GPU machine. The machine stops, and billing ends, as soon as the command exits, hits max_runtime_minutes or is cancelled.