> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotastellar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workloads

> Run, preview, track, and control workloads on the orbital fleet — one API, class-driven.

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       |

<Note>
  **Base URL:** `https://api.rotastellar.com/v1` · **Auth:** `Authorization: Bearer rs_...`
</Note>

## 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".

```bash theme={null}
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}] }
  }'
```

```json theme={null}
{
  "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`.

```json theme={null}
{ "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.

```json theme={null}
{ "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:

```python theme={null}
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"])
```

```bash theme={null}
rotastellar jobs preview --file workload.json
rotastellar jobs submit  --file workload.json
rotastellar jobs get <id>;  rotastellar jobs stages <id>;  rotastellar jobs cancel <id>
```