Skip to Content

Jobs

Long-running work of rookery serve, such as an apply: one run of an action.

OperationKindHTTP
jobs.listcallGET /v1/jobs
jobs.getcallGET /v1/jobs/{id}
jobs.followstreamGET /v1/jobs/{id}
jobs.outputcallGET /v1/jobs/{id}/output
jobs.stopcallPOST /v1/jobs/{id}/stop

jobs.list

The jobs, newest first.

Needs the role view.

Arguments

NameWhereRequiredDescription
subjectquerynoOnly the jobs of this subject: host:HOST, provisioner:PROVISIONER, resource:ID or installation, each by name or id.
hostquerynoOnly the jobs about this host, by name or id, alone or among others, as a roll-out is.
runningquerynoOnly the jobs that have not ended, or with false only those that have.
beforequerynoOnly the jobs that started before the job of this id: the next page after it.
limitquerynoAt most this many (default 100, at most 1,000).

Result

JobInfo[]

Errors

StatusWhen
404before names no job
Request
{
  "id": 1,
  "op": "jobs.list"
}
Reply
{
  "id": 1,
  "result": [
    {
      "id": "k3v9qz2m8w1x",
      "started": "2026-11-12T09:30:00Z"
    }
  ]
}

jobs.get

One job's state.

Needs the role view.

Arguments

NameWhereRequiredDescription
idpathyesA job's id

Result

FieldTypeDescription
action (optional)stringThe action it runs, such as apply, rollout or provision.
arguments (optional)string[]What it was started with, as people may see it: the command of a resource's exec, or an action's arguments as NAME=VALUE. Never a secret argument, a password or standard input.
ended (optional)string | null
exit_code (optional)integer | null
host (optional)stringThe hosts it is about, for a reader: a name, or several with commas.
host_id (optional)stringThe ids of those hosts, as host lists them; a host in a file by its path.
idstring
report (optional)RolloutReport | null
startedstring
stopped_by (optional)string | nullWho stopped it before it ended by itself.
subject (optional)stringWhat it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one.
subject_name (optional)stringWhat it was done to, by name as it is called now: host:NAME, provisioner:NAME, resource:ID or installation; by id for one that is gone.

Errors

StatusWhen
404No such job
Request
{
  "id": 1,
  "op": "jobs.get",
  "args": {
    "id": "j7"
  }
}
Reply
{
  "id": 1,
  "result": {
    "id": "k3v9qz2m8w1x",
    "started": "2026-11-12T09:30:00Z"
  }
}

jobs.follow

A job's output as it is produced.

A stream, as a subscription on the portal or a WebSocket of its own. It resumes from since. Needs the role view.

Arguments

NameWhereRequiredDescription
idpathyesA job's id.
sincequerynoByte offset to start from.

Frames from the server

FrameKindDescription
outputbinaryThe job's output.
exitedJSONThe job ended. The last frame. Example: {"exited":{"exit_code":0}}
Request
{
  "id": 1,
  "op": "jobs.follow",
  "args": {
    "id": "j7",
    "since": "VALUE"
  }
}
Reply
{
  "id": 1,
  "result": {
    "open": true
  }
}

{
  "sub": 1,
  "data": {
    "exited": {
      "exit_code": 0
    }
  }
}

// binary: 00 00 00 01, then the bytes

End the subscription with {"sub": 1, "end": true}.

jobs.output

What a job wrote, by bytes or by lines.

Needs the role view.

Arguments

NameWhereRequiredDescription
idpathyesA job's id
sincequerynoBy bytes: start at this offset.
limitquerynoBy bytes: at most this many (default and most 1 MB).
linequerynoBy lines: start at this line, from 0.
countquerynoBy lines: this many (default 100).
tailquerynoThe last lines.

Result

FieldTypeDescription
data_b64string
endedbooleanNothing more will come.
first_offset (optional)integer | nullWhere what is still kept begins, when the start was dropped.
lines (optional)string[] | nullThe same as text, when read by lines.
next_lineinteger
next_offsetinteger
offsetintegerThe offset this answer starts at.

Errors

StatusWhen
404No such job, or its output is not on this machine, as for a job of an installation restored from its store
Request
{
  "id": 1,
  "op": "jobs.output",
  "args": {
    "id": "j7",
    "since": "VALUE"
  }
}
Reply
{
  "id": 1,
  "result": {
    "data_b64": "aGVsbG8K",
    "ended": true,
    "first_offset": 0,
    "lines": [
      "text"
    ],
    "next_line": 0,
    "next_offset": 0,
    "offset": 0
  }
}

jobs.stop

Stop a running job: its programs end, a session it follows ends on its host, and its record says who stopped it.

Needs the role view.

Arguments

NameWhereRequiredDescription
idpathyesA job's id

Errors

StatusWhen
403The caller may not start a job of its kind, so may not stop it
404No such job
409It has ended already
501It runs in another rookery serve of the same store
Request
{
  "id": 1,
  "op": "jobs.stop",
  "args": {
    "id": "j7"
  }
}
Reply
{
  "id": 1,
  "result": null
}

Types

The named types used on this page.

JobInfo

A job of rookery: one run of an action, with its output kept where it ran.

FieldTypeDescription
action (optional)stringThe action it runs, such as apply, rollout or provision.
arguments (optional)string[]What it was started with, as people may see it: the command of a resource's exec, or an action's arguments as NAME=VALUE. Never a secret argument, a password or standard input.
ended (optional)string | null
exit_code (optional)integer | null
host (optional)stringThe hosts it is about, for a reader: a name, or several with commas.
host_id (optional)stringThe ids of those hosts, as host lists them; a host in a file by its path.
idstring
report (optional)RolloutReport | null
startedstring
stopped_by (optional)string | nullWho stopped it before it ended by itself.
subject (optional)stringWhat it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one.
subject_name (optional)stringWhat it was done to, by name as it is called now: host:NAME, provisioner:NAME, resource:ID or installation; by id for one that is gone.

RolloutReport

The result of a roll-out, host by host in the order they were taken.

FieldTypeDescription
hostsRolloutHost[]
okbooleanEvery host is done or current.

RolloutHost

FieldTypeDescription
changes (optional)Change[]What had changed, as it was before applying.
error (optional)stringWhat went wrong, for a failed host.
namestring
rebooted (optional)booleanIt was rebooted.
stateRolloutStateHow one host of a roll-out went.
warnings (optional)string[]What did not go well without being a failure, such as an update step that ended badly. One stops the roll-out after this host.

Change

Something that changed since a host was applied: rookery itself or a plugin.

FieldTypeDescription
fromstringThe version the host was applied with.
idstringrookery, or a plugin's id.
tostringThe version there is now; empty for a plugin that is gone, the same as from for one whose files changed.

RolloutState

How one host of a roll-out went.

RolloutState

How one host of a roll-out went.

On this page