GET
/
api
/
v3
/
runs
/
{runId}
import { runs } from "@trigger.dev/sdk/v3";

const result = await runs.retrieve("run_1234");

// We include boolean helpers to check the status of the run
// (isSuccess, isFailed, isCompleted, etc.)
if (result.isSuccess) {
  console.log("Run was successful with output", result.output);
}

// You also have access to the run status that includes more granular information
console.log("Run status:", result.status);

// You can access the payload and output
console.log("Payload:", result.payload);
console.log("Output:", result.output);

// You can also access the attempts, which will give you information about errors (if they exist)
for (const attempt of result.attempts) {
  if (attempt.status === "FAILED") {
    console.log("Attempt failed with error:", attempt.error);
  }
}
{
  "id": "run_1234",
  "status": "WAITING_FOR_DEPLOY",
  "taskIdentifier": "my-task",
  "version": 20240523.1,
  "payload": {
    "foo": "bar"
  },
  "output": {
    "foo": "bar"
  },
  "idempotencyKey": "idempotency_key_1234",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "isTest": true,
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z",
  "schedule": {
    "id": "sched_1234",
    "externalId": "user_1234",
    "deduplicationKey": "dedup_key_1234",
    "generator": {
      "type": "CRON",
      "expression": "0 0 * * *",
      "description": "Every day at midnight"
    }
  },
  "attempts": [
    {
      "id": "attempt_1234",
      "status": "PENDING",
      "error": {
        "message": "Something went wrong",
        "name": "Error",
        "stackTrace": "Error: Something went wrong"
      },
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "startedAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization
string
headerrequired

Use your project-specific Secret API key. Will start with tr_dev_, tr_prod, tr_stg, etc.

You can find your Secret API key in the API Keys section of your Trigger.dev project dashboard.

Our TypeScript SDK will default to using the value of the TRIGGER_SECRET_KEY environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the configure function.

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

configure({ secretKey: "tr_dev_1234" });

Path Parameters

runId
string
required

The ID of an run, starts with run_. The run ID will be returned when you trigger a run on a task.

Response

200 - application/json
id
string
required

The unique ID of the run, prefixed with run_

status
enum<string>
required

The status of the run

Available options:
WAITING_FOR_DEPLOY,
QUEUED,
EXECUTING,
REATTEMPTING,
FROZEN,
COMPLETED,
CANCELED,
FAILED,
CRASHED,
INTERRUPTED,
SYSTEM_FAILURE
taskIdentifier
string
required

The identifier of the task that was run

version
string

The version of the worker that executed the run

payload
object

The payload that was sent to the task. Will be omitted if the request was made with a Public API key

output
object

The output of the run. Will be omitted if the request was made with a Public API key

idempotencyKey
string

The idempotency key used to prevent creating duplicate runs, if provided

createdAt
string
required
updatedAt
string
required
isTest
boolean

Whether the run is a test run or not

startedAt
string

The time the run started

finishedAt
string

The time the run finished

schedule
object

The schedule that triggered the run. Will be omitted if the run was not triggered by a schedule

attempts
object[]
required