Skip to content

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.

Updated .md

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 example

Get 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_ID

output#

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_ID

Objects#

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.
Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial