Quickstart

This page submits one job to C1 and reads its telemetry. It takes about 5 minutes once you have an API key.

Preview

During preview the API answers every request with HTTP 503 and the body {"error":"Console access is invite only during preview"}. The calls below are the real calls. They start working the moment your key is activated.

1. Get a key

Request access. When your invitation arrives, create a key in the console under Settings, then export it.

export RACK_API_KEY="rk_live_..."

2. Check capacity

curl -s https://api.racksystems.cloud/v1/capacity \
  -H "Authorization: Bearer $RACK_API_KEY"

A successful response lists each cluster with free GPUs per plan.

{
  "clusters": [
    { "id": "c1", "region": "us-west", "gpu": "h100-sxm-80gb",
      "free": { "on_demand": 2, "batch": 5 }, "reserved_until": null }
  ]
}

3. Submit a job

A job is a container image, a command, a GPU count and a plan.

curl -s https://api.racksystems.cloud/v1/jobs \
  -H "Authorization: Bearer $RACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cluster": "c1",
    "image": "ghcr.io/yourlab/train:latest",
    "command": ["python", "train.py", "--epochs", "3"],
    "gpus": 2,
    "plan": "on_demand",
    "max_minutes": 240
  }'

The same call in Python, with the standard library only:

import json, os, urllib.request

req = urllib.request.Request(
    "https://api.racksystems.cloud/v1/jobs",
    data=json.dumps({
        "cluster": "c1",
        "image": "ghcr.io/yourlab/train:latest",
        "command": ["python", "train.py", "--epochs", "3"],
        "gpus": 2,
        "plan": "on_demand",
        "max_minutes": 240,
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['RACK_API_KEY']}",
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req) as r:
    job = json.load(r)
print(job["id"], job["status"])

4. Read the job

curl -s https://api.racksystems.cloud/v1/jobs/job_01j8x2 \
  -H "Authorization: Bearer $RACK_API_KEY"

Status moves through queued, running, succeeded or failed. The response includes the GPU ids assigned, start and end timestamps, and metered minutes so far.

5. Read telemetry

curl -s "https://api.racksystems.cloud/v1/clusters/c1/telemetry?window=5m" \
  -H "Authorization: Bearer $RACK_API_KEY"

You get one sample per second per GPU: utilization in percent, memory used in GB, temperature in C, power in W. The telemetry page describes the schema and the websocket option for streaming.

Next

Read run a job for image requirements, storage mounts and plans. Read the API reference for every field.