# Claim jobs URL: https://docs.hanzo.ai/docs/openapi/train/post-train-jobs-claim > An executor's long poll for work: it names the machine it runs on, its devices and what its build runs, and is answered, within 25 seconds, one task it can run — a job's lead first; a join once its lead has said where it coordinates — or 204. `POST /v1/train/jobs/claim` > [Train →](https://docs.hanzo.ai/docs/openapi/train) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | ------------------------------------------ | | **Address** | `https://api.hanzo.ai/v1/train/jobs/claim` | | **Method** | `POST` | | **Operation** | `post_train_jobs_claim` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | An executor's long poll for work: it names the machine it runs on, its devices and what its build runs, and is answered, within 25 seconds, one task it can run — a job's lead first; a join once its lead has said where it coordinates — or 204. The answer carries the task's lease, once, which every report for the task must carry; the device-seconds held for it; and how often it must report. An executor acting as a principal of an org claims that org's tasks placed on its machine and can claim no other org's. A platform claim (SuperAdmin alone) is Hanzo's executor: it is answered a task of any org's job that names no machines, its first window held against the job's payer first, and the claim is put on the platform's audit trail. ## Request 9 fields, body `application/json` (required). | Field | In | Type | Required | Description | | ---------------------- | ---- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `bases` | body | string\[] | — | Bases are the base models its trainer runs. | | `devices` | body | string\[] | — | Devices are its accelerators, one entry per device: cuda, rocm, metal, vulkan, cpu. | | `machine` | body | string | — | Machine is the machine claiming, by name: one of the org's linked machines, or for a platform claim the Hanzo host. | | `platform` | body | boolean | — | Platform claims for Hanzo's executor: a task of any org's job that names no machines. | | `supports` | body | train.Supports | — | | | `supports.adaptations` | body | string\[] | — | Adaptations are the modes it runs. | | `supports.outputs` | body | string\[] | — | Outputs are the output kinds it produces. | | `supports.protect` | body | string\[] | — | Protect are the protections it runs: projection, distillation, capabilities. | | `supports.terms` | body | string\[] | — | Terms are the objective terms it runs. | ## Response | Status | Body | Meaning | | --------- | ---------------- | ------- | | `200` | train.Assignment | ok | | `default` | problem-details | refused | `200` body — 90 fields. | Field | In | Type | Always | Description | | --------------------------------- | ---- | ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `job` | body | train.Job | — | | | `job.adaptation` | body | train.Adaptation | — | | | `job.adaptation.alpha` | body | number (double) | — | Alpha is an adapter's scale. | | `job.adaptation.basis` | body | string | — | Basis is a basis artifact, by sha256 or `basis://<base>/<name>`. | | `job.adaptation.chose` | body | train.Chose | — | | | `job.adaptation.chose.mode` | body | string | — | Mode is the mode the job runs. | | `job.adaptation.chose.why` | body | string | — | Why says what decided it. | | `job.adaptation.mode` | body | string | — | Mode is full, readout (the head alone, over the frozen base), lora, qlora, basis or auto. | | `job.adaptation.rank` | body | integer (int64) | — | Rank is an adapter's rank, or how many of a basis's directions are used. | | `job.adaptation.residual_rank` | body | integer (int64) | — | ResidualRank is the rank of an orthonormal residual learned beside a basis's coefficients; 0 trains the coefficients alone. | | `job.adaptation.sources` | body | string\[] | — | Sources are lora artifacts (sha256) a basis is built from, in place of Basis. | | `job.adaptation.targets` | body | string\[] | — | Targets are the modules an adapter or a basis attaches to. | | `job.artifacts` | body | train.artifact\[] | — | Artifacts are its outputs. | | `job.artifacts[].created` | body | integer (int64) | — | Created is when it was registered, unix seconds. | | `job.artifacts[].job` | body | string | — | Job is the job that produced it; empty for an upload. | | `job.artifacts[].kind` | body | string | — | Kind is checkpoint, lora, capability, basis or merged, or dataset for an upload. | | `job.artifacts[].meta` | body | any | — | Meta describes it: its base and revision, its modules, a basis's address. | | `job.artifacts[].name` | body | string | — | Name labels it. | | `job.artifacts[].sha256` | body | string | — | SHA256 is the hex digest of its bytes, and its name in the object store. | | `job.artifacts[].size` | body | integer (int64) | — | Size is its byte count. | | `job.artifacts[].state` | body | string | — | State is pending until its bytes are read back, then stored; deleted once the org deleted it or it outlived its retention unpublished. | | `job.base_model` | body | string | — | | | `job.created` | body | integer (int64) | — | Created, Started and Ended are unix seconds; 0 is not yet. | | `job.created_by` | body | string | — | CreatedBy is the principal that created it. | | `job.dataset` | body | train.Dataset | — | | | `job.dataset.splits` | body | object | — | Splits maps a role (train, validation) to the dataset's own split name. | | `job.dataset.splits.*` | body | string | — | | | `job.dataset.uri` | body | string | — | URI names the data. | | `job.ended` | body | integer (int64) | — | | | `job.error` | body | string | — | Error says why a job failed or stopped. | | `job.evaluation` | body | train.Evaluation | — | | | `job.evaluation.suites` | body | string\[] | — | Suites are the suites the job is meant to improve. | | `job.from` | body | string | — | | | `job.id` | body | string | — | ID names the job. | | `job.objective` | body | train.Objective | — | | | `job.objective.loss` | body | string | — | Loss is `cross_entropy`. | | `job.objective.terms` | body | train.Term\[] | — | Terms are added to each row's loss. | | `job.objective.terms[].kind` | body | string | — | Kind names the term. | | `job.objective.terms[].margin` | body | number (double) | — | Margin is a hinge's margin, in logits. | | `job.objective.terms[].weight` | body | number (double) | — | Weight scales it; 0 is off. | | `job.output` | body | train.Output | — | | | `job.output.kind` | body | string | — | Kind is checkpoint, lora, capability, basis or merged. | | `job.output.name` | body | string | — | Name labels it. | | `job.project` | body | string | — | Project is the creator's project scope. | | `job.protect` | body | train.Protect | — | | | `job.protect.budget` | body | train.Budget | — | | | `job.protect.budget.accuracy` | body | number (double) | — | Accuracy is the largest accuracy drop allowed. | | `job.protect.budget.ece` | body | number (double) | — | ECE is the largest calibration-error rise allowed. | | `job.protect.capabilities` | body | string\[] | — | Capabilities are capability artifacts, by sha256. | | `job.protect.distillation` | body | boolean | — | Distillation adds KL to the base's answers on a preservation set drawn from the suites. | | `job.protect.projection` | body | train.Projection | — | | | `job.protect.projection.strength` | body | number (double) | — | Strength is λ in \[0, 1]; absent is 1, the whole of P g removed. | | `job.protect.suites` | body | string\[] | — | Suites are capabilities the base already has, by suite. | | `job.published` | body | any | — | Published is the publish record, once published. | | `job.resources` | body | train.Resources | — | | | `job.resources.budget` | body | integer (int64) | — | Budget bounds what the job's compute costs, in US cents; 0 is none beyond the payer's balance. | | `job.resources.devices` | body | string\[] | — | Devices are the accelerator kinds the job may run on — cuda, rocm, metal, vulkan, cpu; none named is any its base runs. | | `job.resources.machines` | body | string\[] | — | Machines are the org's linked machines by name; the first leads. | | `job.resources.max_seconds` | body | integer (int64) | — | MaxSeconds bounds the device-seconds the job's tasks use together; 0 is none. | | `job.resources.steps` | body | integer (int64) | — | Steps bounds optimizer steps; 0 runs the plan. | | `job.result` | body | any | — | Result is the lead's evaluation and verdict, once reported. | | `job.revision` | body | string | — | | | `job.started` | body | integer (int64) | — | | | `job.status` | body | string | — | Status is queued, running, evaluating, succeeded, rejected, failed, cancelled or stopped. | | `job.tasks` | body | train.TaskView\[] | — | Tasks are its units of execution. | | `job.tasks[].device` | body | string | — | Device is the accelerator class it runs on — gpu or cpu — and Devices how many. | | `job.tasks[].devices` | body | integer (int64) | — | | | `job.tasks[].held` | body | integer (int64) | — | | | `job.tasks[].host` | body | string | — | Host is the machine that claimed it. | | `job.tasks[].id` | body | string | — | ID names the task. | | `job.tasks[].machine` | body | string | — | Machine is the machine it was placed on, or empty for any. | | `job.tasks[].role` | body | string | — | Role is lead or join. | | `job.tasks[].seconds` | body | integer (int64) | — | Seconds are the device-seconds its reports metered, and Held those held for it. | | `job.tasks[].seen` | body | integer (int64) | — | Seen is its last report, unix seconds. | | `job.tasks[].status` | body | string | — | Status is open, claimed, done or lost. | | `job.usage` | body | train.Usage | — | | | `job.usage.cost_micro_usd` | body | integer (int64) | — | CostMicroUSD is what Seconds were charged, in micro-USD: 0 on the org's own machines. | | `job.usage.held` | body | integer (int64) | — | Held are the device-seconds held beyond Seconds; 0 once it ended. | | `job.usage.seconds` | body | integer (int64) | — | Seconds are the device-seconds used. | | `org` | body | string | — | Org is the job's org. | | `task` | body | train.Claimed | — | | | `task.coordinator` | body | string | — | Coordinator is where a join task reaches its lead. | | `task.device` | body | string | — | Device is the accelerator kind it runs on, and Devices how many of them. | | `task.devices` | body | integer (int64) | — | | | `task.held` | body | integer (int64) | — | Held is the device-seconds held for it. | | `task.id` | body | string | — | ID names the task. | | `task.job` | body | string | — | Job names its job. | | `task.lease` | body | string | — | Lease authenticates every report for the task; it is answered once. | | `task.report` | body | integer (int64) | — | Report is the most seconds that may pass between its reports. | | `task.role` | body | string | — | Role is lead or join. | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** `hanzo` has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK. **SDK** **.ts** ```ts import { Configuration, TrainApi } from 'hanzoai'; const api = new TrainApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.postTrainJobsClaim({ bases: [""], devices: [""] }); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import TrainApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = TrainApi(client).post_train_jobs_claim(bases=[""], devices=[""]) ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.TrainAPI.PostTrainJobsClaim(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, train_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = train_api::post_train_jobs_claim(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.TrainApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new TrainApi(client).postTrainJobsClaim(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/train/jobs/claim \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "bases": [ "" ], "devices": [ "" ] }' ``` **MCP** MCP declares no tool for **train** — `tools/list` on `https://api.hanzo.ai/v1/mcp` names the products it does reach. Use HTTP or an SDK. --- [Train API](https://docs.hanzo.ai/docs/openapi/train) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)