Runs

List a job’s runs or a whole project’s, and read one run with each of its attempts.

Three functions read runs: runs() for one job, allRuns() for the whole project, and getRun() for one run with each of its attempts. Runs are kept for 30 days.

runs()

Lists a job’s runs from the last 30 days, newest first.

function runs(id: string, options?: CallOptions): Paged<Run>

Parameters

idstringRequired: The job’s ID: 26 lowercase letters and digits.
options.signalAbortSignal: Cancels every request the list makes.
options.timeoutMsnumber: How long each page may take, in milliseconds. The timeoutMs set in createSpace when you leave it out, 30,000 by default.

Returns

A Paged<Run> of runs, straight away rather than a promise. Nothing is fetched until you read it: walk it with for await, collect it with all(), or read one page of up to 200 runs with page(cursor). See list() for how paging works.

Errors

Code	When
`validation_failed`	`id` is not a job ID
`not_found`	The project has no job with that ID

allRuns()

Lists the runs of every job in the project from the last 30 days, newest first. Narrow it by job, status, or how the run started.

function allRuns(
  filter?: CallOptions & {
    job?: string
    status?: RunStatus
    trigger?: "schedule" | "manual"
  }
): Paged<Run>

Parameters

filter.jobstring: Only this job’s runs. A job ID: 26 lowercase letters and digits.
filter.statusstring: Only runs with this status: pending, running, retry_wait, succeeded, failed, or cancelled. See Run statuses.
filter.triggerstring: Only runs started this way: schedule, or manual for run().
filter.signalAbortSignal: Cancels every request the list makes.
filter.timeoutMsnumber: How long each page may take, in milliseconds. The timeoutMs set in createSpace when you leave it out, 30,000 by default.

The filter is checked when the list is read, not when allRuns() is called, so a bad filter rejects the first for await, all(), or page() with validation_failed.

Returns

A Paged<Run> of runs, which pages the same way as runs().

Errors

Code	When
`validation_failed`	A filter field is not one listed above, or its value is not allowed

getRun()

Reads one run with each of its attempts.

function getRun(job: string, run: string, options?: CallOptions): Promise<RunDetail>

Parameters

jobstringRequired: The ID of the job the run belongs to: 26 lowercase letters and digits.
runstringRequired: The run’s ID: 26 lowercase letters and digits.
options.signalAbortSignal: Cancels the call.
options.timeoutMsnumber: How long the call may take, in milliseconds. The timeoutMs set in createSpace when you leave it out, 30,000 by default.

Returns

A promise of the run with attemptList, one entry for each attempt. See With its attempts.

Errors

Code	When
`validation_failed`	`job` or `run` is not an ID
`not_found`	The project has no such job, or the job has no such run

Other errors

Every function here is sent again, up to retries times, when it fails in a way that may pass, such as a network failure or 503. Each can also fail with the codes shared by all of space, such as missing_project or network_error. See SpaceError.

Example

failed-runs.ts

import { space } from "digitospace"

for await (const run of space.schedule.allRuns({ status: "failed" })) {
  const detail = await space.schedule.getRun(run.jobId, run.id)
  const last = detail.attemptList.at(-1)
  console.log(run.jobId, run.scheduledFor, last?.errorClass, last?.statusCode)
}

Last updated 30 September 2026