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
Number of results per page. Defaults to 20.
Return runs created after this run ID. Used for forward pagination.
Return runs created before this run ID. Used for backward pagination.
Filter by run status. Accepted values: PENDING_VERSION, QUEUED, EXECUTING, REATTEMPTING, FROZEN, COMPLETED, CANCELED, FAILED, CRASHED, INTERRUPTED, SYSTEM_FAILURE.
Filter by one or more task identifiers.
Filter by one or more tags attached to runs.
Return runs created at or after this date-time.
Return runs created at or before this date-time.
Filter by worker version, e.g. ["20240523.1"].
When true, return only test runs. When false, exclude test runs.
Filter by schedule ID (e.g. sched_1234).
Filter by bulk action ID.
Endpoint (Personal Access Token)
GET https://api.trigger.dev/api/v1/projects/{projectRef}/runs
The project reference, e.g. proj_yubjwjsfkxnylobaqvqz.
Filter by environment. One or more of dev, staging, prod.
Response
Array of run summary objects.
Unique run ID, prefixed with run_.
Worker version that executed the run.
Environment info: id, name, and optionally user.
Idempotency key, if provided.
Whether this is a test run.
Tags attached to the run.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
ISO 8601 timestamp when execution started.
ISO 8601 timestamp when the run finished.
If delayed, when the run will be enqueued.
Compute cost in cents (not applicable to DEV runs).
Invocation cost in cents (not applicable to DEV runs).
Total compute duration in milliseconds (excludes waits).
Cursor pagination handles.
Run ID to pass as page[after] for the next page.
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);
}
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
}
}
