Skip to content

Running jobs with JobSpecs🔗

A JobSpec is the modern way to run a computation on the Apheris platform. It bundles everything a job needs — the datasets, the model, resources and the job arguments — into a single unit that you create, monitor and control with the apheris jobspec commands (see the Apheris CLI specification for the full reference).

JobSpecs are the v2 jobs pipeline. The previous job pipeline (apheris compute create followed by apheris job schedule) is deprecated as of Apheris 3.12 and will be removed in a future version — see Migrating from v1 jobs.

Creating a job🔗

A job is created from two inputs: a spec describing what to run on, and a payload with the arguments for the model. Both are given as a path to a JSON file or as an inline JSON string.

spec.json:

{
    "datasets": [
        "medical-decathlon-task004-hippocampus-a_gateway-1_org-1",
        "medical-decathlon-task004-hippocampus-b_gateway-2_org-2"
    ],
    "model": { "id": "apheris-nnunet", "version": "x.y.z" },
    "resources": { "server": { "cpu": 1, "memory": 2000 } }
}

payload.json — the job arguments, which are defined by the model (see the model's guide for its expected fields):

{ "mode": "training", "model_configuration": "2d", "dataset_id": 4, "num_rounds": 1 }

Create the job and wait for it to finish:

apheris jobspec create --spec spec.json --payload payload.json --wait

Useful options:

  • --wait blocks until the job reaches a terminal status; --timeout (default 600 seconds) and --poll-interval (default 5 seconds) tune the wait.
  • --idempotency-key makes creation replay-safe: submitting the same key again returns the existing JobSpec.
  • --queue-id runs jobs that share a queue ID one at a time, reusing a warm compute spec instead of activating a new one for every job.
  • --description stores a free-text description on the JobSpec.

Checking status and troubleshooting🔗

apheris jobspec list
apheris jobspec status --job-id <id> --verbose
apheris jobspec logs --job-id <id>

list shows your jobs (with --all, also jobs from others in your organisation, subject to your role). status --verbose adds timing and execution steps. logs retrieves the logs as columns or NDJSON (--format json), printed to stdout or written to a file (--storage-path). Logs remain retrievable after a job has finished.

When a job fails and you need to understand what happened, the activity log shows the compute status events of every gateway, in order:

$ apheris jobspec compute-statuses --job-id <id>

[2026-10-09T14:03:12Z] [gateway-1] creating
[2026-10-09T14:04:02Z] [gateway-1] running
[2026-10-09T14:15:41Z] [gateway-1] failed  The compute client on gateway-1 was OOMKilled

Each line is one transition of the computation on that gateway, with the message explaining it. If a site is restarted or killed — for example by the OOM killer — the transitions leading up to the failure appear here, with the reason on the final line.

Getting the results🔗

By default, the compute spec behind a job is deactivated as soon as the job finishes, and its output is deleted with it. To download a job's output after it completes, create the job with --no-auto-cleanup and release the spec once you have the results:

apheris jobspec create --spec spec.json --payload payload.json --no-auto-cleanup --wait
apheris jobspec download results
apheris jobspec cleanup

cleanup releases every idle compute spec you own, not only the one behind this job, and releasing a spec deletes its results. Download everything you need before running it.

Jobs can also produce data artifacts — results that outlive the job and can be shared with other organisations (see Artifacts Overview). List the artifacts a job produced and download them with:

apheris jobspec artifacts --job-id <id>
apheris artifacts download --artifact-id <artifact-id>

Aborting and cleaning up🔗

apheris jobspec abort --job-id <id> aborts a running job. abort-all aborts every job matching criteria such as status or queue ID.

apheris jobspec cleanup releases every idle compute spec you own, not only those of a specific job — run it after downloading all results you need (see Getting the results).

Migrating from v1 jobs🔗

The v1 pipeline — apheris compute create followed by apheris job schedule — is deprecated as of Apheris 3.12 and will be removed in a future version. The --use-v2 flags on the apheris job commands are deprecated as well; apheris jobspec replaces them.

Compute Specs remain the underlying resource concept — see Compute Specs. What changes is how jobs are submitted and tracked: JobSpecs combine both steps in one command, add queueing and idempotency, and give better status information per gateway.