Claim jobs

POST /v1/train/jobs/claim

Train → · All API references → · Get started →

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.

Examples

CLI

SDK

HTTP

MCP

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

.ts

.py

.go

.rs

.java

import { Configuration, TrainApi } from 'hanzoai';

const api = new TrainApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postTrainJobsClaim({ bases: ["<bases>"], devices: ["<devices>"] });

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=["<bases>"], devices=["<devices>"])

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
}

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?;

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();

curl -X POST https://api.hanzo.ai/v1/train/jobs/claim \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "bases": [
         "<bases>"
       ],
       "devices": [
         "<devices>"
       ]
     }'

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 · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousPublish jobs NextCreate jobs