Jobs

Every submission becomes a job, whatever it carried and wherever it runs. One job model, one set of states, one result contract.

States

State	Kind
queued	in flight
validating	in flight
running	in flight
succeeded	terminal
failed	terminal
canceled	terminal
expired	terminal

A job leaves an in-flight state exactly once and never returns to one. succeeded and failed are the two outcomes; canceled is your decision; expired means the retention window passed before the result was fetched.

Cancelling a job that has already finished is job_not_cancelable rather than a silent success, so a client cannot believe it stopped something that had already run.

Events

A job reports what it did, in order:

validated, qc, subsampled, model_loaded, predicted, written

These are how you find out that a run subsampled your tiles, or how far a long job has got, without waiting for it to end. They are also written beside the result, so the record survives the job.

Runtimes

gpu, cpu

Which runtime a job uses is decided by the model's card, not by the request. Capacity is finite and one job per key is in flight at a time; every job response carries its position in the queue and an estimate, so waiting is something you can plan around rather than poll blindly.

If the queue is at its bound the submission is refused with queue_full, and if the runtime a model needs is not accepting work it is lane_disabled. Both carry a retry interval. Both are honest answers about capacity, and both are better than a job that is accepted and sits forever.

Submitting the same thing twice

The header is Idempotency-Key and its scope is per_key_while_job_lives.

Re-sending an identical request under the same key returns the same job instead of starting a second one — which is what makes a retry after a timeout safe. Re-using the key with a different payload is idempotency_conflict, because the only alternative would be to silently ignore one of the two things you asked for.

The result

One .h5ad, the same layout whichever runtime ran it.

Part	Contract
Format	h5ad
Gene axis index	ensembl_gene_id
Gene axis columns	feature_name, hgnc_id, biotype, measured_in_training, n_train_datasets, model_token
Extra matrices	bulk_calibrated, image_only
Provenance keys	model, input_spec, job

The provenance keys record the model, the input_spec it enforced and the job, so a file found on a disk two years from now can still say what produced it.

Downloading before a job is terminal is result_not_ready; downloading after the retention window is result_expired. See Privacy and retention.