Workloads

A workload is a unit of compute you run on the satellite fleet. There is one submission surface — POST /v1/workloads — and the workload’s class decides how it executes:

`parallelism.class`	Runs as
`single` (default)	one satellite (the CAE places it)
`data-parallel`	sharded across satellites, recombined on the ground
`spatial`	each satellite processes its footprint of an area-of-interest
`federated`	a global model trained from on-board data (only deltas leave orbit)
`model-parallel`	a pipeline split across satellites — activations flow stage → stage
`split-learning`	a head on the data-owning satellite, the heavy tail offloaded

Base URL: https://api.rotastellar.com/v1 · Auth: Authorization: Bearer rs_...

Lifecycle

preview (optional) → submit → poll GET /{id} → inspect stages / artifacts → cancel (any time).

Preview — the plan

POST /v1/workloads/preview returns the CAE’s verdict — feasibility, the model cut/partition, whether it’s ISL-bound — and a cost estimate, without running anything (read-only; no quota, no billing). It’s the “plan” to submit’s “apply”.

curl -X POST https://api.rotastellar.com/v1/workloads/preview \
  -H "Authorization: Bearer $RS_API_KEY" -H "content-type: application/json" -d '{
    "placement": { "satellites": [25544, 48274, 53807] },
    "parallelism": { "class": "model-parallel", "stages": 3 },
    "model": { "layers": [{"name":"embed","compute_fwd":2,"activation_mb":4}] }
  }'

{
  "kind": "model_parallel",
  "candidates": 3,
  "plan": { "feasible": true, "stages": 3, "partition": [/* ... */], "isl_bound": false },
  "cost_estimate": { "ocu": 450, "cents": 5400, "per_stage_ocu": 150, "stages": 3, "price_per_ocu_cents": 12 }
}

distributed-training is ISL-bound (gradient AllReduce over sparse inter-satellite links), so it is preview-only — preview it to see the honest verdict; it is not executable.

Submit — run

POST /v1/workloads takes the same body and executes it. Returns the id + a status_url.

{ "id": "wl_9a0b…", "status": "scheduling", "status_url": "/v1/workloads/wl_9a0b…" }

A frontier workload (model-parallel / split-learning) runs as a pipeline across the constellation — the CAE places each stage on a satellite, and the stages run in sequence as a coordinated pipeline.

Track status

Poll GET /v1/workloads/{id} and read phase: submitted → scheduling → dispatching → awaiting_report → done (or failed / timed_out / canceled). workflow_status is the coarse pill (RUNNING / COMPLETED / FAILED / …). The response also carries placement, the structured outcome, the result manifest, and cost once billable.

Stages — per-satellite execution

GET /v1/workloads/{id}/stages — for a frontier / scatter-gather workload, which satellite ran each stage and its status.

{ "id": "wl_9a0b…", "stages": [
  { "index": 0, "satellite": "48274", "satellite_name": "CSS (TIANHE)", "status": "done", "role": "stage" },
  { "index": 1, "satellite": "25544", "satellite_name": "ISS (ZARYA)",  "status": "done", "role": "stage" }
] }

Results & cancel

GET /v1/workloads/{id}/artifacts — the result manifest (the outputs + how to fetch each: custodied contentId or external uri).
POST /v1/workloads/{id}/cancel — stop a queued or running workload; its queued / in-flight stages are dropped.

SDKs & CLI

Every operation is in the SDKs and the CLI:

rs.workloads.preview(placement={...}, parallelism={"class": "model-parallel", "stages": 3}, model={...})
wl = rs.workloads.submit(type="fine-tune", placement={...}, parallelism={...}, model={...})
rs.workloads.get(wl["id"]); rs.workloads.stages(wl["id"]); rs.workloads.cancel(wl["id"])

rotastellar jobs preview --file workload.json
rotastellar jobs submit  --file workload.json
rotastellar jobs get <id>;  rotastellar jobs stages <id>;  rotastellar jobs cancel <id>

Overview

CAE

Deployments

Sim

Workloads

Lifecycle

Preview — the plan

Submit — run

Track status

Stages — per-satellite execution

Results & cancel

SDKs & CLI

​Lifecycle

​Preview — the plan

​Submit — run

​Track status

​Stages — per-satellite execution

​Results & cancel

​SDKs & CLI

Lifecycle

Preview — the plan

Submit — run

Track status

Stages — per-satellite execution

Results & cancel

SDKs & CLI