Retrieve Run

Overview

Returns full information about a run, including its status, payload, output, metadata, and all attempt history. If authenticated with a Public API key, payload and output are omitted for security.

Endpoint

GET https://api.trigger.dev/api/v3/runs/{runId}

Path parameters

string

required

The unique run ID, prefixed with run_.

Response

string

Unique run ID, prefixed with run_.

string

Current status. One of: PENDING_VERSION, DELAYED, QUEUED, EXECUTING, REATTEMPTING, FROZEN, COMPLETED, CANCELED, FAILED, CRASHED, INTERRUPTED, SYSTEM_FAILURE.

string

The task that was run.

string

Worker version that executed the run.

string

Idempotency key used when triggering, if provided.

boolean

Whether this is a test run.

object

The payload passed to the task (omitted for Public API keys).

object

The output returned by the task (omitted for Public API keys).

object

Key-value metadata attached to the run.

string[]

Tags attached to the run.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

string

When execution started.

string

When the run finished.

string

If delayed, when the run will be enqueued.

string

Time-to-live set on the run, if any.

string

If the TTL elapsed before execution, when the run expired.

number

Compute cost in cents (excludes DEV).

number

Invocation cost in cents (excludes DEV).

number

Total compute time in ms (excludes waits).

integer

Depth in the task hierarchy. Root runs have depth 0.

string

Batch ID if this run was created as part of a batch.

string

One of trigger, triggerAndWait, batchTrigger, batchTriggerAndWait.

Runs related to this one in the task hierarchy.

Show relatedRuns fields

object

The root run of the hierarchy (if not the root itself).

object

The parent run (if not the root).

object[]

Immediate child runs.

object

Schedule that triggered the run, if applicable.

Show schedule fields

string

Schedule ID, prefixed with sched_.

string

Optional external ID set when creating the schedule.

string

Deduplication key of the schedule.

object

CRON generator info: type, expression, description.

object[]

History of all execution attempts.

Show attempt fields

string

Attempt ID, prefixed with attempt_.

string

One of PENDING, EXECUTING, PAUSED, COMPLETED, FAILED, CANCELED.

object

Error details if the attempt failed: message, name, stackTrace.

string

ISO 8601 creation timestamp.

string

When the attempt started.

string

When the attempt completed.

Examples

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

const run = await runs.retrieve("run_p4omhh45hgxxnq1re6ovy");

// Convenience boolean helpers
if (run.isSuccess) {
  console.log("Output:", run.output);
} else if (run.isFailed) {
  console.log("Failed. Last attempt error:", run.attempts.at(-1)?.error);
}

console.log("Status:", run.status);
console.log("Payload:", run.payload);

for (const attempt of run.attempts) {
  if (attempt.status === "FAILED") {
    console.log("Attempt failed:", attempt.error);
  }
}

curl "https://api.trigger.dev/api/v3/runs/run_p4omhh45hgxxnq1re6ovy" \
  -H "Authorization: Bearer tr_dev_1234"

Response example

{
  "id": "run_p4omhh45hgxxnq1re6ovy",
  "status": "COMPLETED",
  "taskIdentifier": "my-task",
  "version": "20240523.1",
  "isTest": false,
  "payload": { "message": "Hello, world!" },
  "output": { "result": "done" },
  "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,
  "depth": 0,
  "attempts": [
    {
      "id": "attempt_1234",
      "status": "COMPLETED",
      "createdAt": "2024-04-01T12:00:01Z",
      "startedAt": "2024-04-01T12:00:01Z",
      "completedAt": "2024-04-01T12:00:05Z"
    }
  ]
}

Overview

Tasks & Runs

Schedules & Queues

Waitpoints & Env Vars

Overview

Endpoint

Path parameters

Response

Examples

Response example

​Overview

​Endpoint

​Path parameters

​Response

​Examples

​Response example

Overview

Endpoint

Path parameters

Response

Examples

Response example