Jobs
Long-running work of rookery serve, such as an apply: one run of an action.
| Operation | Kind | HTTP |
|---|---|---|
jobs.list | call | GET /v1/jobs |
jobs.get | call | GET /v1/jobs/{id} |
jobs.follow | stream | GET /v1/jobs/{id} |
jobs.output | call | GET /v1/jobs/{id}/output |
jobs.stop | call | POST /v1/jobs/{id}/stop |
jobs.list
The jobs, newest first.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
subject | query | no | Only the jobs of this subject: host:HOST, provisioner:PROVISIONER, resource:ID or installation, each by name or id. |
host | query | no | Only the jobs about this host, by name or id, alone or among others, as a roll-out is. |
running | query | no | Only the jobs that have not ended, or with false only those that have. |
before | query | no | Only the jobs that started before the job of this id: the next page after it. |
limit | query | no | At most this many (default 100, at most 1,000). |
Result
JobInfo[]
Errors
| Status | When |
|---|---|
| 404 | before names no job |
{
"id": 1,
"op": "jobs.list"
}{
"id": 1,
"result": [
{
"id": "k3v9qz2m8w1x",
"started": "2026-11-12T09:30:00Z"
}
]
}jobs.get
One job's state.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A job's id |
Result
| Field | Type | Description |
|---|---|---|
action (optional) | string | The 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) | string | The hosts it is about, for a reader: a name, or several with commas. |
host_id (optional) | string | The ids of those hosts, as host lists them; a host in a file by its path. |
id | string | |
report (optional) | RolloutReport | null | |
started | string | |
stopped_by (optional) | string | null | Who stopped it before it ended by itself. |
subject (optional) | string | What it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one. |
subject_name (optional) | string | What 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
| Status | When |
|---|---|
| 404 | No such job |
{
"id": 1,
"op": "jobs.get",
"args": {
"id": "j7"
}
}{
"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
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A job's id. |
since | query | no | Byte offset to start from. |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
output | binary | The job's output. |
exited | JSON | The job ended. The last frame. Example: {"exited":{"exit_code":0}} |
{
"id": 1,
"op": "jobs.follow",
"args": {
"id": "j7",
"since": "VALUE"
}
}{
"id": 1,
"result": {
"open": true
}
}
{
"sub": 1,
"data": {
"exited": {
"exit_code": 0
}
}
}
// binary: 00 00 00 01, then the bytesEnd the subscription with {"sub": 1, "end": true}.
jobs.output
What a job wrote, by bytes or by lines.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A job's id |
since | query | no | By bytes: start at this offset. |
limit | query | no | By bytes: at most this many (default and most 1 MB). |
line | query | no | By lines: start at this line, from 0. |
count | query | no | By lines: this many (default 100). |
tail | query | no | The last lines. |
Result
| Field | Type | Description |
|---|---|---|
data_b64 | string | |
ended | boolean | Nothing more will come. |
first_offset (optional) | integer | null | Where what is still kept begins, when the start was dropped. |
lines (optional) | string[] | null | The same as text, when read by lines. |
next_line | integer | |
next_offset | integer | |
offset | integer | The offset this answer starts at. |
Errors
| Status | When |
|---|---|
| 404 | No such job, or its output is not on this machine, as for a job of an installation restored from its store |
{
"id": 1,
"op": "jobs.output",
"args": {
"id": "j7",
"since": "VALUE"
}
}{
"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
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A job's id |
Errors
| Status | When |
|---|---|
| 403 | The caller may not start a job of its kind, so may not stop it |
| 404 | No such job |
| 409 | It has ended already |
| 501 | It runs in another rookery serve of the same store |
{
"id": 1,
"op": "jobs.stop",
"args": {
"id": "j7"
}
}{
"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.
| Field | Type | Description |
|---|---|---|
action (optional) | string | The 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) | string | The hosts it is about, for a reader: a name, or several with commas. |
host_id (optional) | string | The ids of those hosts, as host lists them; a host in a file by its path. |
id | string | |
report (optional) | RolloutReport | null | |
started | string | |
stopped_by (optional) | string | null | Who stopped it before it ended by itself. |
subject (optional) | string | What it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one. |
subject_name (optional) | string | What 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.
| Field | Type | Description |
|---|---|---|
hosts | RolloutHost[] | |
ok | boolean | Every host is done or current. |
RolloutHost
| Field | Type | Description |
|---|---|---|
changes (optional) | Change[] | What had changed, as it was before applying. |
error (optional) | string | What went wrong, for a failed host. |
name | string | |
rebooted (optional) | boolean | It was rebooted. |
state | RolloutState | How 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.
| Field | Type | Description |
|---|---|---|
from | string | The version the host was applied with. |
id | string | rookery, or a plugin's id. |
to | string | The 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.
How one host of a roll-out went.