---
title: "Estimate Job"
method: POST
path: "/usage/estimate"
tags: ["usage"]
---

# Estimate Job

`POST /usage/estimate`

## Request

- Base URL: `https://api.os3robotics.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.os3robotics.com/usage/estimate`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Prices a job as POST /jobs would take it, before it exists. 403 as POST /jobs for a
workspace or dataset version it could not use, and for LLM training your organisation's
LLM plan does not include; 422 for a base or GPU without an estimate, or a base that does
not train on the dataset version.

## Request body

- JobCreate
  - `workspace_id` string, uuid, required
  - `spec` JobSpec, required: What to train. The image comes from the server-side catalog by `base`, never from the tenant; dataset details (id, manifest sha256, SAS) are resolved at launch.
    - `dataset_version_id` string, uuid, required
    - `base` 'pi05' | 'smolvla' | 'groot' | 'molmoact2' | 'openvla_oft' | 'xr1' | 'lora_trl' | 'halo_rft' | 'halo_rlvr'
    - `steps` integer, required
    - `batch` integer
    - `use_rabc` boolean
    - `intervention_weighting` 'sirius' | 'iwr', nullable
    - `recap` boolean
    - `rl2` 'practice' | 'adaptation', nullable
    - `use_depth` boolean
    - `gpu` string
    - `providers` string[]
    - `lora` LoraSpec: A LoRA run (base `lora_trl`); `JobSpec.steps` / `batch` are its max_steps / batch. `trainer` picks what trains it, Halo or TRL; unset, OS3's default trainer for the base. `base_model` is a key of the base-model catalog (GET /jobs/bases), checked when the job is submitted. `parent`, when set, is an adapter version of the workspace, trained on the same base at the same revision with a verified receipt, that the run continues: its LoRA starts from that adapter (same rank and alpha), and a DPO run (TRL) takes it as its reference model. `seed`: the training seed (data order, adapter initialisation, dropout), so runs that differ only in it can be compared; unset, 0. `budget_h100_hours`: a session's budget in a shared allocation (required there, refused elsewhere): the most H100-hours its share of the allocation may reach; the session is stopped at it. `trainable`: `lora` (the default), or `full` to train the model's own weights, which no base offers yet. `bundle`: an SFT job with Halo trains up to that many consecutive steps of one agent run as one row, each step's answer trained as its own row would be; unset, one step a row. `context_parallel`: an SFT job with Halo splits each row longer than 32,768 tokens over 2, 4 or 8 GPUs, as many as its longest row needs; unset, off.
      - `objective` 'sft' | 'dpo', required
      - `base_model` string, required
      - `rank` integer
      - `alpha` integer
      - `learning_rate` number
      - `trainer` 'halo' | 'trl', nullable
      - `mode` 'final' | 'reasoning', nullable
      - `parent` string, uuid, nullable
      - `seed` integer, nullable
      - `budget_h100_hours` number, nullable
      - `trainable` 'lora' | 'full'
      - `bundle` integer, nullable
      - `context_parallel` boolean
    - `rlvr` RlvrSpec: Online RLVR on Halo (base `halo_rlvr`): LoRA GRPO against an executable task's verifier. `recipe` names a frozen recipe (environment and verifier, rewards, sampling, GRPO objective, rollout server): sql_v3, the default, or sql_v2 (SQL tasks in OS3's task environments, LoRA on every linear layer; sql_v3's hidden variants skip a foreign key that names no parent key), support_v1, structured_v1 or graded_v2 (sql_v3's contract on the support, structured and graded environments), structured_v2 (structured_v1 with extraction semantics) or harness_v1 (a customer's harness, live against its declared staging system), sql_v4_dapo_sync (sql_v3's training on the same environment, with every setting that decides what trains fixed by the recipe itself, defaults included), sql_v4_dapo_async1 (that training with each round's rollouts sampled while the step before it trains, at most one update behind, on two or more rollout servers: `rollout_replicas`), sql_v4_cispo_reuse2 (that training with CISPO's loss, each round's rollouts trained by two optimizer updates), graded_v3_gspo_reuse2 (graded_v2's training with GSPO's loss and the same reuse), sql_v4_dapo_sync_r3 (sql_v4_dapo_sync whose trainer replays the rollout engine's expert routing, on a MoE base only: Qwen3.6-35B-A3B), sql_v4_dapo_sync_lora (sql_v4_dapo_sync whose rollout server serves the trained LoRA unmerged instead of folded into its bf16 base weights), sql_v4_dapo_r3_122b (sql_v4_dapo_sync_r3 at an 8,192-token context, rows of at most 4,096 tokens, sampling without thinking and at most 6 turns: the only recipe of Qwen3.5-122B-A10B, which trains no other), code_contests_v4 (Halo's code_contests, the model's programs run on OS3's isolated runtime), bridged_v1 (a bridged environment, below), bridged_v2 (bridged_v1 with each episode trained as one whole-trajectory row instead of a row per assistant turn: long multi-turn episodes) or bridged_v3 (bridged_v2 without its 32-turn ceiling: the package's own max_turns and the base's context bound an episode) or bridged_v4 (bridged_v3 training rows of at most 49,152 tokens, a longer one masked: Qwen3.6-35B-A3B's expert-parallel trainer's ceiling on H100 80 GB) or bridged_v5 (bridged_v4 rewarding an episode's strict pass less 0.5 when its calls broke a check that held before, every turn's reasoning sent back to the rollout server as OS3 serves a thinking student, turns of up to 16,384 tokens, rows of at most 32,768). code_contests_v1, code_contests_v2, code_contests_v3, sql_v1, graded_v1 and sql_v4_cispo_sync are retired: new jobs are refused them. `JobSpec.steps` is its max_steps and `JobSpec.batch` its episodes per step per trainer GPU (a multiple of the recipe's group size). The job's GPUs (`JobSpec.gpu`) split into two roles: the last `rollout_gpus` serve rollouts, the others train; unset on a base of more than one catalog `gpus` (Qwen3.6-35B-A3B's 2: its rollout server's tensor-parallel GPUs), `rollout_gpus` is that many (else the workspace's pipeline default, 1 unless set), and such a base trains on at least that many and serves on that many a server (JobSpec.unfit). `rollout_replicas`: how many separate rollout servers those GPUs run, each on an equal share of them (1 unless set; a recipe that collects rollouts while it trains needs at least 2); every GPU is billed for the whole run, idle or not. A checkpoint every `save_steps` steps is what a relaunch resumes from. `base_model` is a key of the base-model catalog, checked at submission like LoraSpec's. `parent`, as LoraSpec's: the adapter version the run starts from, which its rollouts sample too. `budget_h100_hours` (required for a new job, on every paid LLM plan): the most H100-hours the run may take; it is quoted and reserved at no more, and stops there, keeping its last checkpoint as its adapter with its receipt. The budget must cover the run up to its first checkpoint (`save_steps`) and the time to publish it. `seed`, as LoraSpec's. `env_revision` (recipes bridged_v1 to bridged_v5 only, and required by them): the environment hub revision of a bridged environment (an OpenEnv, verifiers, NeMo Gym or AutomationBench package of the workspace's own catalog, qualified for training) the run trains on, its train split, through OS3's episode channel. `warmup` and `retention`: a public bridged revision qualified for training, trained for at most `steps` of the run's steps before the task (at most 20% of the steps and of the budget) or after it (at most 10% of the steps after the warm-up and of the tokens the task and retention train). `judge`: a calibrated rubric judge's reward beside the task's checks (not with a code recipe). `trainable`, as LoraSpec's. `mode`: the student mode (`final`: thinking off, `reasoning`: on) the rollouts sample in, the one the child is served in; unset, the recipe's own sampling. `context_parallel`: every row split over the trainer GPUs, one context-parallel group of 2 or 4 (a dense base's LoRA), for episodes longer than one GPU holds; unset, off.
      - `recipe` 'code_contests_v1' | 'code_contests_v2' | 'code_contests_v3' | 'code_contests_v4' | 'sql_v1' | 'sql_v2' | 'sql_v3' | 'support_v1' | 'structured_v1' | 'graded_v1' | 'graded_v2' | 'structured_v2' | 'harness_v1' | 'sql_v4_dapo_sync' | 'sql_v4_cispo_sync' | 'sql_v4_dapo_async1' | 'sql_v4_cispo_reuse2' | 'graded_v3_gspo_reuse2' | 'bridged_v1' | 'sql_v4_dapo_sync_r3' | 'sql_v4_dapo_sync_lora' | 'sql_v4_dapo_r3_122b' | 'bridged_v2' | 'bridged_v3' | 'bridged_v4' | 'bridged_v5'
      - `base_model` string, required
      - `rollout_gpus` integer
      - `rollout_replicas` integer
      - `rank` integer
      - `alpha` integer
      - `learning_rate` number
      - `save_steps` integer
      - `parent` string, uuid, nullable
      - `budget_h100_hours` number, nullable
      - `seed` integer, nullable
      - `env_revision` string, uuid, nullable
      - `warmup` PublicPhase: A public bridged environment revision of the environment hub, qualified for training, that a customer task's RLVR run trains on for at most `steps` of its steps: before its task (`warmup`: at most 20% of the run's steps and budget) or after it (`retention`: at most 10% of the steps after the warm-up, and of the tokens the task and retention train).
        - `env_revision` string, uuid, required
        - `steps` integer, required
      - `retention` PublicPhase: A public bridged environment revision of the environment hub, qualified for training, that a customer task's RLVR run trains on for at most `steps` of its steps: before its task (`warmup`: at most 20% of the run's steps and budget) or after it (`retention`: at most 10% of the steps after the warm-up, and of the tokens the task and retention train).
        - `env_revision` string, uuid, required
        - `steps` integer, required
      - `judge` JudgeReward: A rubric judge's reward beside the task's own checks. The judge model marks each criterion met or not on the final answer; the share met, times `weight` (at most half the checks' weight), adds to the reward. The judge must first be calibrated as automatable for `task_id` with these criteria, context and model: at least 200 labelled answers per criterion, agreement at least 0.80 at its 95% lower bound, at most 10% of verdicts flipped on a second read. An answer the judge cannot score leaves its group of rollouts out of the update rather than scoring 0. A run whose rewards the judge gives more and more to answers the checks fail is stopped, and keeps no adapter. An adapter trained this way is released on the task's exact checks or on a judge from another vendor.
        - `task_id` string, uuid, required
        - `criteria` JudgeCriterion[], required
          - `name` string, required
          - `description` string, required
        - `context` string, nullable
        - `model` string
        - `weight` number
      - `trainable` 'lora' | 'full'
      - `mode` 'final' | 'reasoning', nullable
      - `context_parallel` boolean
    - `rft` RftSpec: Hosted RFT on Halo (base `halo_rft`): rejection-sampling fine-tuning, OS3's default training method for a task with a verifier (RLVR, base `halo_rlvr`, is the upgrade). One job on one GPU samples the base `samples` times on each of the first `tasks` tasks of an RLVR dataset version in `recipe`'s task environment (sql_v3 unless the job names another), keeps up to 4 distinct episodes per task that the verifier passed, and trains a LoRA on every assistant turn of them: `JobSpec.steps` / `batch` are its max_steps / batch, and rank, alpha and learning_rate are LoraSpec's. Its defaults: 8 samples of each of 1,024 tasks, LoRA rank 16 at a learning rate of 2e-4. `base_model` is a key of the base-model catalog, checked at submission like LoraSpec's. `parent`, as LoraSpec's: the adapter version that samples the tasks and whose LoRA the run trains on. `seed`, as LoraSpec's: the fine-tuning's. `env_revision` (recipe bridged_v1 only, and required by it): the environment hub revision of a bridged environment of the workspace's own catalog, qualified for training, whose train split the job samples. `trainable`, as LoraSpec's. `mode`, as RlvrSpec's: the student mode it samples in, so its rows carry thinking only in `reasoning`.
      - `recipe` 'sql_v3' | 'sql_v2' | 'support_v1' | 'structured_v1' | 'graded_v1' | 'graded_v2' | 'structured_v2' | 'harness_v1' | 'bridged_v1'
      - `base_model` string, required
      - `samples` integer
      - `tasks` integer
      - `rank` integer
      - `alpha` integer
      - `learning_rate` number
      - `parent` string, uuid, nullable
      - `seed` integer, nullable
      - `env_revision` string, uuid, nullable
      - `trainable` 'lora' | 'full'
      - `mode` 'final' | 'reasoning', nullable
    - `max_runtime_s` integer, nullable
    - `pilot` PilotArm: An arm of a technique pilot, or its winner's confirmation run: set by the pilot.
      - `id` string, uuid, required
      - `salt` string, required
      - `samples` integer, required
      - `eval_s` integer, required
      - `confirm` boolean
    - `resume_from` ResumeFrom: The verified checkpoint a recovery run resumes from. Set only by OS3's recovery: a job you create with it is refused.
      - `job_id` string, uuid, required
      - `incident_id` string, uuid, required
      - `checkpoint_id` string, uuid, required
      - `step` integer, required
      - `manifest_sha256` string, required

## Response `200`

Successful Response

- EstimateOut
  - `seconds` string, required
  - `gpu_seconds` string, required
  - `sku` string, required
  - `h100_seconds` string, required
  - `h100_seconds_max` string, required
  - `remaining_h100_seconds` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/os3robotics/apis/os3-api.md) - [All operations](https://skmtc.dev/os3robotics/apis/os3-api/llms.txt) - [OpenAPI document](https://skmtc.dev/os3robotics/apis/os3-api/revisions/af32cd4f14bb?raw)