JobRun API reference
One run of a job: a machine made at one of its times, deleted when its command ends. Its record (exit code, times, the last 256 KiB of its output) stays readable for 7 days after.
Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.
Its states: starting, running, paused, deleted, error.
Endpoints#
| Method | Path | Description |
|---|---|---|
GET |
/v2/job-runs |
List jobRuns |
GET |
/v2/job-runs/{id} |
Get a jobrun |
GET |
/v2/job-runs/{id}/output |
output |
List jobRuns#
GET /v2/job-runs
Lists a job's runs, oldest first unless order is newest, deleted ones included while their records are kept.
Its action, for a key's grant: jobRuns:list.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
job |
string | Yes | Its job, by ID. |
order |
one of oldest, newest |
No | newest first, or oldest first. Default: "oldest". |
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 JobRun, and next, where the next page starts, none on the last.
In v1: GET /v1/jobs/{id}/runs.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/job-runs?job=example" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobRuns.list({ job: "example" });Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.job_runs.list(job="example")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.job_runs.list(job: "example")Terminalruntime jobRuns list --job exampleGet a jobrun#
GET /v2/job-runs/{id}
Returns a run.
Its action, for a key's grant: jobRuns:get.
Path: id.
Returns a JobRun.
In v1: GET /v1/job-runs/{id}.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/job-runs/JOBRUN_ID" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobRuns.get("JOBRUN_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.job_runs.get("JOBRUN_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.job_runs.get("JOBRUN_ID")Terminalruntime jobRuns get JOBRUN_IDoutput#
GET /v2/job-runs/{id}/output
Returns a run's output after a cursor, stdout and stderr together in the order written, and the cursor to read on from. Its last 256 KiB are kept; truncated says when the cursor fell before them.
Its action, for a key's grant: jobRuns:read.
Path: id.
Query:
| Field | Type | Required | Description |
|---|---|---|---|
cursor |
integer | No | Output after this byte. At least 0. Default: 0. |
maxBytes |
integer | No | At most this many bytes. At least 1. At most 262144. Default: 65536. |
Returns a JobRunOutput.
In v1: GET /v1/job-runs/{id}/logs.
Examples:
Terminalcurl -X GET "https://api.withruntime.com/v2/job-runs/JOBRUN_ID/output" \ -H "Authorization: Bearer $RUNTIME_API_KEY"TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.jobRuns.output("JOBRUN_ID");Pythonfrom withruntime import Runtimeruntime = Runtime() # RUNTIME_API_KEY from the environmentresult = runtime.job_runs.output("JOBRUN_ID")rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.job_runs.output("JOBRUN_ID")Terminalruntime jobRuns output JOBRUN_IDObjects#
JobRun
One run of a job: a machine made at one of its times, deleted when its command ended.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Its ID. |
object |
one of job.run |
Yes | Always job.run. |
job |
string | Yes | Its job's ID. |
state |
one of starting, running, paused, deleted, error |
Yes | Its machine's state: starting and running while it runs, deleted once it ended, error when it failed to start. |
at |
string (RFC 3339) | Yes | The time it is for: its schedule's, or when it was asked for. |
attempt |
integer | Yes | Its attempt at that time, from 1. |
manual |
boolean | Yes | Someone asked for it (run), rather than its schedule. |
createdAt |
string (RFC 3339) | Yes | When it was made. |
endedAt |
string (RFC 3339) | No | When its command ended. |
exitCode |
integer | No | Its command's exit code, once it ended; none for one a signal or its timeout ended, or one deleted before its end. |
succeeded |
boolean | Yes | It ended with exit code 0. |
outputBytes |
integer | No | How many bytes its command wrote, stdout and stderr together. |
OutputChunk
Some of a process's output.
| Field | Type | Required | Description |
|---|---|---|---|
offset |
integer | Yes | Where it starts in the process's output. |
stream |
one of stdout, stderr |
Yes | The stream it was written to. |
text |
string | Yes | It, as text. |
base64 |
string (base64) | No | It, as bytes, when the process answers base64. |
JobRunOutput
A run's output, stdout and stderr together in the order written, after a cursor: its last 256 KiB are kept.
| Field | Type | Required | Description |
|---|---|---|---|
chunks |
list of OutputChunk | Yes | The output, in the order it was written. |
nextCursor |
integer | Yes | The cursor to read on from. |
truncated |
boolean | Yes | Output before what is kept was dropped, past the cursor. |
complete |
boolean | Yes | The run ended and nothing is left past the next cursor. |