Job API reference
A command run in a fresh machine, once or on a cron schedule in a timezone. Each run is a machine made at its time, deleted when its command ends, and billed as any machine is; its exit code and its last 256 KiB of output are kept. Runs of one job never overlap: a time that comes while one runs is made once it ends, and times missed make one run.
Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.
Its states: scheduled, paused, finished, deleted.
Endpoints#
| Method | Path | Description |
|---|---|---|
POST |
/v2/jobs |
Create a job |
GET |
/v2/jobs/{id} |
Get a job |
GET |
/v2/jobs |
List jobs |
DELETE |
/v2/jobs/{id} |
Delete a job |
POST |
/v2/jobs/{id}:pause |
pause |
POST |
/v2/jobs/{id}:resume |
resume |
POST |
/v2/jobs/{id}:update |
update |
POST |
/v2/jobs/{id}:run |
run |
Create a job#
POST /v2/jobs
Creates a job. Its first run is made at its schedule's first time. Asked again with the same Idempotency-Key, it returns the same job.
Its action, for a key's grant: jobs:create.
Body: a JobCreate.
Returns a Job.
In v1: POST /v1/jobs.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/jobs" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.create();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.create()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.createTerminalruntime jobs createGet a job#
GET /v2/jobs/{id}
Returns a job.
Its action, for a key's grant: jobs:get.
Path: id.
Returns a Job.
In v1: GET /v1/jobs/{id}.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/jobs/JOB_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.get("JOB_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.get("JOB_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.get("JOB_ID")Terminalruntime jobs get JOB_IDList jobs#
GET /v2/jobs
Lists the project's jobs, newest first.
Its action, for a key's grant: jobs:list.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
label |
list of string | No | Only those with every label given (repeat it for several): key:value, or a key for any value. |
cursor |
string | No | Where the page starts: a page's next. |
limit |
integer | No | The most items the page holds. At least 1. At most 200. Default: 50. |
Returns a page: items, each a Job, and next, where the next page starts, none on the last.
In v1: GET /v1/jobs.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/jobs" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.list();Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.list()rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.listTerminalruntime jobs listDelete a job#
DELETE /v2/jobs/{id}
Deletes a job: no run is made from then on, and a run in flight is ended. Its runs' records stay readable for 7 days.
Its action, for a key's grant: jobs:delete.
Path: id.
Returns a Job.
In v1: POST /v1/jobs/{id}:cancel.
Examples:
Terminalcurl -X DELETE "https://api.withruntime.com/v2/jobs/JOB_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.delete("JOB_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.delete("JOB_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.delete("JOB_ID")Terminalruntime jobs delete JOB_IDpause#
POST /v2/jobs/{id}:pause
Pauses a job: no run is made at its times until it is resumed. A run in flight runs to its end.
Its action, for a key's grant: jobs:pause.
Path: id.
Returns a Job.
In v1: POST /v1/jobs/{id}:pause.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/jobs/JOB_ID:pause" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.pause("JOB_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.pause("JOB_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.pause("JOB_ID")Terminalruntime jobs pause JOB_IDresume#
POST /v2/jobs/{id}:resume
Resumes a paused job: its next run is made at its schedule's next time from now.
Its action, for a key's grant: jobs:wake.
Path: id.
Returns a Job.
In v1: POST /v1/jobs/{id}:resume.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/jobs/JOB_ID:resume" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.resume("JOB_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.resume("JOB_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.resume("JOB_ID")Terminalruntime jobs resume JOB_IDupdate#
POST /v2/jobs/{id}:update
Changes a job's settings: each one named replaces its own, the rest are kept. Runs made from then on use them; one in flight runs as it was made. A new schedule's next run is at its next time from now.
Its action, for a key's grant: jobs:update.
Path: id.
Body: a JobSettings.
Returns a Job.
In v1: POST /v1/jobs/{id}:update.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/jobs/JOB_ID:update" \ -H "Authorization: Bearer $RUNTIME_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.update("JOB_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.update("JOB_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.update("JOB_ID")Terminalruntime jobs update JOB_IDrun#
POST /v2/jobs/{id}:run
Makes a run now, beside its schedule; a paused job stays paused. Refused 409 while a run of it is in flight. Asked again with the same Idempotency-Key, it makes nothing more.
Its action, for a key's grant: jobs:exec.
Path: id.
Returns a Job.
In v1: POST /v1/jobs/{id}:trigger.
Examples:
Terminalcurl -X POST "https://api.withruntime.com/v2/jobs/JOB_ID:run" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobs.run("JOB_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.jobs.run("JOB_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.jobs.run("JOB_ID")Terminalruntime jobs run JOB_IDObjects#
JobSchedule
When a job runs: once, at at; or at each time of its cron in its timezone. One of the two.
| Field | Type | Required | Description |
|---|---|---|---|
at |
string (RFC 3339) | No | The one time it runs. |
cron |
string | No | A cron expression of five fields (minute, hour, day of month, month, day of week), as cron reads them, or @hourly, @daily, @weekly, @monthly or @yearly. |
timezone |
string | No | The IANA timezone its cron's times are in (America/Denver), daylight saving included; UTC when omitted. |
SandboxRun
A command a sandbox runs once it starts: when it ends, the sandbox stops.
| Field | Type | Required | Description |
|---|---|---|---|
cmd |
string (run by bash -lc) or list of strings (the program and its arguments) |
Yes | The command: text, run by bash -lc, or the program and its arguments as a list, run without a shell. |
cwd |
string | No | The directory it runs in; the user's home when omitted. |
env |
object of strings | No | Environment variables to add. |
timeoutSeconds |
number | No | Seconds it may run before it is stopped (1.5 for 1,500 ms); no limit when omitted or 0. At least 0. |
JobRetry
How a failed run is run again: a run that ends with an exit code other than 0, or at its timeout.
| Field | Type | Required | Description |
|---|---|---|---|
maxAttempts |
integer | No | Attempts in all for one time, the first included; 1 (no retry) when omitted. At least 1. At most 10. Default: 1. |
backoffSeconds |
integer | No | Seconds from a failed attempt's end to the next. At least 0. At most 86400. Default: 30. |
JobSecrets
Which of its org's secrets each run gets, and under which variables.
| Field | Type | Required | Description |
|---|---|---|---|
only |
list of string | No | The secrets each run gets in their own variables, by name: only those of them whose scope admits it; [] none. At most 64 items. |
env |
object of strings | No | Variables each holding the value of one of the org's visible secrets whose scope admits the run, by the secret's name, only or not: {"WEBSITE_TOKEN": "CRON_SECRET"}. |
VolumeMount
A volume a machine attaches at its create, mounted read-write in it, one machine at a time; detached when the machine is deleted.
| Field | Type | Required | Description |
|---|---|---|---|
volume |
string | Yes | The volume, by name or ID, in the machine's project. |
path |
string | Yes | Where it is mounted, such as /data: an absolute path, not under /proc, /sys, /dev, /etc, /usr, /bin, /sbin, /lib or /boot. |
JobSettings
A job's settings: what each of its runs is made with.
| Field | Type | Required | Description |
|---|---|---|---|
schedule |
JobSchedule | No | When it runs. |
run |
SandboxRun | No | The command each run runs; the run ends when it ends. |
retry |
JobRetry | No | How a failed run is run again; never when omitted. |
secrets |
JobSecrets | No | Which of its org's secrets each run gets; every one whose scope admits it when omitted. |
vcpu |
integer | No | Each run's vCPUs. At least 1. Default: 1. |
memoryGB |
number | No | Each run's memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (0.5). At least 1. Default: 1. |
diskGB |
number | No | Each run's disk in GB, to the MiB, over a fresh copy of its image. At least 1. Default: 4. |
image |
string | No | The image each run boots, by name (its newest version), name:version or ID; Runtime's default image when omitted. |
user |
one of runtime, root |
No | Who its command runs as: runtime (uid 1000, with passwordless sudo) or root. Its image's when omitted, else runtime. |
volumes |
list of VolumeMount | No | Volumes each run attaches and mounts, at most one, in the job's project; a run waits while another machine holds it. |
maxCost |
string (US dollars, decimal) | No | The most one run may cost, in US dollars ("0.50"): a run pauses once it has cost that, as a machine at its maxCost does. |
JobCreate
A job to create: its schedule and run are required.
| Field | Type | Required | Description |
|---|---|---|---|
schedule |
JobSchedule | No | When it runs. |
run |
SandboxRun | No | The command each run runs; the run ends when it ends. |
retry |
JobRetry | No | How a failed run is run again; never when omitted. |
secrets |
JobSecrets | No | Which of its org's secrets each run gets; every one whose scope admits it when omitted. |
vcpu |
integer | No | Each run's vCPUs. At least 1. Default: 1. |
memoryGB |
number | No | Each run's memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (0.5). At least 1. Default: 1. |
diskGB |
number | No | Each run's disk in GB, to the MiB, over a fresh copy of its image. At least 1. Default: 4. |
image |
string | No | The image each run boots, by name (its newest version), name:version or ID; Runtime's default image when omitted. |
user |
one of runtime, root |
No | Who its command runs as: runtime (uid 1000, with passwordless sudo) or root. Its image's when omitted, else runtime. |
volumes |
list of VolumeMount | No | Volumes each run attaches and mounts, at most one, in the job's project; a run waits while another machine holds it. |
maxCost |
string (US dollars, decimal) | No | The most one run may cost, in US dollars ("0.50"): a run pauses once it has cost that, as a machine at its maxCost does. |
name |
string | No | Its name, unique in its project. |
labels |
labels (keys under runtime. are Runtime's) |
No | Labels to find it by; each run carries them. |
Job
A job.
| Field | Type | Required | Description |
|---|---|---|---|
schedule |
JobSchedule | No | When it runs. |
run |
SandboxRun | No | The command each run runs; the run ends when it ends. |
retry |
JobRetry | No | How a failed run is run again; never when omitted. |
secrets |
JobSecrets | No | Which of its org's secrets each run gets; every one whose scope admits it when omitted. |
vcpu |
integer | No | Each run's vCPUs. At least 1. Default: 1. |
memoryGB |
number | No | Each run's memory in GB (1 GB is 1,024 MiB); a fraction is taken to the MiB (0.5). At least 1. Default: 1. |
diskGB |
number | No | Each run's disk in GB, to the MiB, over a fresh copy of its image. At least 1. Default: 4. |
image |
string | No | The image each run boots, by name (its newest version), name:version or ID; Runtime's default image when omitted. |
user |
one of runtime, root |
No | Who its command runs as: runtime (uid 1000, with passwordless sudo) or root. Its image's when omitted, else runtime. |
volumes |
list of VolumeMount | No | Volumes each run attaches and mounts, at most one, in the job's project; a run waits while another machine holds it. |
maxCost |
string (US dollars, decimal) | No | The most one run may cost, in US dollars ("0.50"): a run pauses once it has cost that, as a machine at its maxCost does. |
id |
string | Yes | Its ID. |
object |
one of job |
Yes | Always job. |
name |
string | No | Its name, unique in its project. |
state |
one of scheduled, paused, finished, deleted |
Yes | Where it is: scheduled (its runs are made at their times), paused (none is), finished (its one time ran). |
labels |
labels (keys under runtime. are Runtime's) |
Yes | Its labels. |
nextRunAt |
string (RFC 3339) | No | When its next run is made, or its next retry; none when paused or finished. |
createdAt |
string (RFC 3339) | No | When it was created. |
revision |
integer | No | Its revision, changed by every change to it. |
deletedAt |
string (RFC 3339) | No | When it was deleted: a delete's answer, its state deleted. |