List Runs

Overview

Returns a cursor-paginated list of runs for an environment. Filter by status, task identifier, tags, date range, and more. Two variants exist:

Endpoint	Auth	Scope
`GET /api/v1/runs`	Secret key	Current environment only
`GET /api/v1/projects/{projectRef}/runs`	PAT	All environments in a project

Endpoint (secret key)

GET https://api.trigger.dev/api/v1/runs

Query parameters

integer

Number of results per page. Defaults to 20.

string

Return runs created after this run ID. Used for forward pagination.

string

Return runs created before this run ID. Used for backward pagination.

string[]

Filter by run status. Accepted values: PENDING_VERSION, QUEUED, EXECUTING, REATTEMPTING, FROZEN, COMPLETED, CANCELED, FAILED, CRASHED, INTERRUPTED, SYSTEM_FAILURE.

string[]

Filter by one or more task identifiers.

string[]

Filter by one or more tags attached to runs.

string (ISO 8601)

Return runs created at or after this date-time.

string (ISO 8601)

Return runs created at or before this date-time.

string[]

Filter by worker version, e.g. ["20240523.1"].

boolean

When true, return only test runs. When false, exclude test runs.

string

Filter by schedule ID (e.g. sched_1234).

string

Filter by bulk action ID.

Endpoint (Personal Access Token)

GET https://api.trigger.dev/api/v1/projects/{projectRef}/runs

string

required

The project reference, e.g. proj_yubjwjsfkxnylobaqvqz.

Supports all of the same query filters above, plus:

string[]

Filter by environment. One or more of dev, staging, prod.

Response

object[]

Array of run summary objects.

Show Run object fields

string

Unique run ID, prefixed with run_.

string

Current run status.

string

The task that was run.

string

Worker version that executed the run.

object

Environment info: id, name, and optionally user.

string

Idempotency key, if provided.

boolean

Whether this is a test run.

string[]

Tags attached to the run.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

string

ISO 8601 timestamp when execution started.

string

ISO 8601 timestamp when the run finished.

string

If delayed, when the run will be enqueued.

number

Compute cost in cents (not applicable to DEV runs).

number

Invocation cost in cents (not applicable to DEV runs).

number

Total compute duration in milliseconds (excludes waits).

object

Cursor pagination handles.

Show pagination fields

string

Run ID to pass as page[after] for the next page.

string

Run ID to pass as page[before] for the previous page.

Examples

import { runs } from "@trigger.dev/sdk";

// Fetch first page
let page = await runs.list({ limit: 20 });

for (const run of page.data) {
  console.log(`${run.id}: ${run.status}`);
}

// Manual pagination
while (page.hasNextPage()) {
  page = await page.getNextPage();
}

// Auto-paginate through all results
for await (const run of runs.list({ limit: 20 })) {
  console.log(run.id);
}

import { runs } from "@trigger.dev/sdk";

const response = await runs.list({
  status: ["QUEUED", "EXECUTING"],
  taskIdentifier: ["my-task", "my-other-task"],
  from: new Date("2024-04-01T00:00:00Z"),
  to: new Date(),
});

for (const run of response.data) {
  console.log(`${run.id}: ${run.status}`);
}

import { runs, configure } from "@trigger.dev/sdk";

configure({ secretKey: process.env["TRIGGER_ACCESS_TOKEN"] }); // tr_pat_…

const response = await runs.list("proj_yubjwjsfkxnylobaqvqz", {
  env: ["prod", "staging"],
  status: ["FAILED"],
});

curl "https://api.trigger.dev/api/v1/runs?status=COMPLETED&limit=20" \
  -H "Authorization: Bearer tr_dev_1234"

Response example

{
  "data": [
    {
      "id": "run_p4omhh45hgxxnq1re6ovy",
      "status": "COMPLETED",
      "taskIdentifier": "my-task",
      "version": "20240523.1",
      "env": { "id": "cl1234", "name": "prod" },
      "isTest": false,
      "tags": ["user_5df987al13"],
      "createdAt": "2024-04-01T12:00:00Z",
      "updatedAt": "2024-04-01T12:00:05Z",
      "startedAt": "2024-04-01T12:00:01Z",
      "finishedAt": "2024-04-01T12:00:05Z",
      "durationMs": 4200,
      "costInCents": 0.00292,
      "baseCostInCents": 0.0025
    }
  ],
  "pagination": {
    "next": "run_earlier123",
    "previous": null
  }
}

Overview

Tasks & Runs

Schedules & Queues

Waitpoints & Env Vars

Overview

Endpoint (secret key)

Query parameters

Endpoint (Personal Access Token)

Response

Examples

Response example

​Overview

​Endpoint (secret key)

​Query parameters

​Endpoint (Personal Access Token)

​Response

​Examples

​Response example

Overview

Endpoint (secret key)

Query parameters

Endpoint (Personal Access Token)

Response

Examples

Response example