---
title: "A job's status; with `?wait=60`, held until it finishes."
method: GET
path: "/v1/jobs/{job_id}"
tags: ["jobs"]
---

# A job's status; with \`?wait=60\`, held until it finishes.

`GET /v1/jobs/{job_id}`

## Request

- Base URL: `https://api.japanfold.aiand.com`
- URL: `https://api.japanfold.aiand.com/v1/jobs/{job_id}`
- Auth: one of:
  - none
  - HTTP bearer

With `wait`, the request is held open until the job leaves `queued`/`running` or `wait` seconds pass, whichever is first, and the body is the same job resource either way. Loop on it instead of sleeping: each call returns the moment the job is done. When too many callers are already held the job's current state comes back at once with `Retry-After`; `Preference-Applied: wait` means the hold happened.

## Path parameters

- `job_id` string, required

## Query parameters

- `wait` integer

## Response `200`

Job

- Job
  - `artifacts` object[]: Present on a succeeded job read by its id (not in the list), when it has at most 20 files: the same entries as `artifacts` in its results. A job with more files lists them only in its results.
  - `attempt` integer: Present only when the job's structure is on its second run, because the box running it stopped answering (hung, or its agent died); its progress started over. A job of several structures carries it on the retried entry of targets. Billed once.
  - `created_at` string, date-time, nullable
  - `done` integer
  - `download` string: Present on a succeeded job read by its id: one shell command that fetches every result file into the current directory, reading the key from `JAPANFOLD_API_KEY`. Past 20 files it fetches and unzips the archive instead.
  - `email_when_done` boolean: Present once POST /v1/jobs/{id}/notify has been asked.
  - `error` string, nullable: Why the job failed; on a succeeded job, what it could not deliver (see partial).
  - `finished_at` string, date-time, nullable
  - `id` string, required
  - `kind` 'predict' | 'design' | 'embed', required
  - `links` object
  - `model` string, nullable
  - `name` string
  - `object` 'job', required
  - `partial` object: Present only on a succeeded job that delivered less than it was asked for, because a design shard or a target failed. What did finish is in the results and was billed; error says what was lost.
    - `delivered` integer
    - `requested` integer: designs you would get back (the smaller of budget and num_designs), or structures submitted
    - `shards` integer
    - `shards_failed` integer
    - `unit` 'designs' | 'structures'
  - `progress` number, nullable: 0..1, or null when indeterminate
  - `protocol` string, nullable
  - `queue` object: Present while any of the job's tasks waits for a chip. Facts, never a time: how long the work ahead takes is not known until it ends. The next free chip goes to the account holding the fewest chips, then the one that used the least in the last hours; an account's own jobs run in the order it sent them.
    - `reason` 'busy': On a submit's 429, why: the queue ahead of the submission was longer than the API will hold a request open for, so it was refused rather than admitted late. Nothing is written and nothing is charged. Honour `Retry-After`.
  - `results_ready` boolean
  - `stage` string, nullable
  - `started_at` string, date-time, nullable
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
  - `total` integer
  - `waiting_for_device` boolean: Present and true only while the job has been accepted but no processor is free for it yet. The job is queued, not stalled.

## Other responses

- `400`: Invalid request
- `401`: Unauthorized
- `404`: Not found

---

[API](https://skmtc.dev/aiand/apis/japanfold-api.md) · [All operations](https://skmtc.dev/aiand/apis/japanfold-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aiand/apis/japanfold-api/revisions/9f4be813b447?raw)