List the detached jobs on a machine

Returns the machine's jobs — running right now, plus finished ones still retained (about a week; expired jobs are then swept automatically in the background, roughly hourly, driven by job start/list activity — so this very call can be what deletes an older expired job's metadata, log and workspace). Use it to answer 'what is running on the GPU box?', to recover the jobId of work started earlier, or before starting new GPU work so you don't collide with an existing run. Newest first, and by default only the newest 20 — 7 days of retention on a busy machine can mean dozens of records, and returning them all wastes a caller's context; raise limit (page cap 200) or narrow with status when you need more, and the reply reports how many older entries were omitted. If the reply carries skippedJobs/warning, the list is INCOMPLETE — some records were dropped and are not shown.

get/api/v1/jobs

Request

  • Base URL: https://aicommander.dev
  • URL: https://aicommander.dev/api/v1/jobs
  • Auth: one of:
    • none
    • HTTP bearer

Query parameters

codestring required
Example:AIC-7K3P-WX9M-RTBN

How the user named the machine, passed exactly as given: an AIC- session code, or — with an API key — a saved alias/hostname.

operation_idstring

Look up the one job started with this operation_id instead of listing: the reply is then {ok:true, job} (a JobSummary), and 404 not_found means nothing was accepted under that id (or its record was already pruned — the id is remembered only while the job record exists, about 7 days after the job ends). Other filters are ignored.

status'running' | 'exited' | 'unknown'

Only return jobs in this state. Omit for every retained job. Validated, not ignored: any other value is rejected with 400 naming the field, because a misspelt filter used to return the unfiltered newest page — which reads exactly like a filtered one.

include_command'true' | 'false'

Send true to also return each job's command line. Off by default so command strings are not echoed back unnecessarily.

limitinteger

Return only the newest N jobs. Default 20, minimum 1, page cap 200 — validated, not clamped: a value outside that range is rejected with 400 naming the field. Anything older than the newest N is left out, and the reply reports how many in omitted.

Response

The machine's jobs.

oktrue required
omittedinteger

How many older job records are NOT in jobs. THE LIST IS A PAGE, NOT THE HISTORY: with no limit you get the newest 20, and this field is the only thing that says so — a client that ignores it will read a capped list as the machine's complete job history. 0 means nothing was left out. With a status filter it is an UPPER bound (the machine stops walking at the first N matches and cannot know how many of the records behind them would have matched). Raise limit (up to 200) or narrow with status to reach the rest. Omitted entirely only when the machine is running an agent too old to report it — then the completeness of the list is simply unknown.

warningstring

Present exactly when skippedJobs is — the same omission in prose, for a human or a model reading the response. Surface it to the user rather than presenting the shortened list as complete.

Example response

{
  "jobs": [
    {
      "jobId": "9f2c1b7ad4e05386"
    }
  ],
  "skippedJobs": [
    {
      "field": "job.endedAt",
      "jobId": "9f2c1b7ad4e05386"
    }
  ],
  "warning": "WARNING: 1 job record on this machine did not match the protocol and is NOT listed here: job 9f2c1b7ad4e05386 (bad field: job.endedAt). The list above is therefore incomplete."
}

Changes

No recorded changes to this operation across all 1 revision of this API.