Run Context (ctx)

The ctx (context) object provides information about the current run. It is passed as the second argument to every task's run function and does not change during execution.

Usage

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

export const myTask = task({
  id: "my-task",
  run: async (payload: { message: string }, { ctx }) => {
    console.log(ctx.run.id);           // run ID
    console.log(ctx.attempt.number);   // attempt number
    console.log(ctx.environment.type); // "PRODUCTION" | "STAGING" | etc.
  },
});

Context Properties

ctx.task

Property	Type	Description
id	string	Task identifier
exportName	string	Exported function name
filePath	string	File path of the task

ctx.attempt

Property	Type	Description
id	string	Execution attempt ID
number	number	Attempt number (1 = first try)
startedAt	Date	When this attempt started
status	string	Current attempt status
backgroundWorkerId	string	Worker ID

ctx.run

Property	Type	Description
id	string	Run ID
tags	string[]	Tags attached to this run
isTest	boolean	Whether this is a test run
createdAt	Date	Run creation time
startedAt	Date	Run start time
idempotencyKey	string?	Idempotency key if set
maxAttempts	number	Max retry attempts allowed
durationMs	number	Duration in ms (fixed at call time)
costInCents	number	Cost in cents (fixed at call time)
version	string	Code version this run is locked to
maxDuration	number?	Max allowed duration in seconds

ctx.queue

Property	Type	Description
id	string	Queue ID
name	string	Queue name

ctx.environment

Property	Type	Description
id	string	Environment ID
slug	string	Environment slug
type	string	PRODUCTION | STAGING | DEVELOPMENT | PREVIEW
branchName	string?	Branch name (preview environments only)

ctx.git

Property	Description
commitSha	Full commit SHA
commitRef	Branch or tag ref
commitMessage	Commit message
commitAuthorName	Author name
dirty	Whether there are uncommitted changes
remoteUrl	Git remote URL
pullRequestNumber	PR number (if applicable)
pullRequestTitle	PR title
pullRequestState	open | closed | merged

ctx.organization

Property	Description
id, slug, name	Organization identifiers

ctx.project

Property	Description
id, ref, slug, name	Project identifiers

ctx.machine

Property	Description
name	Machine preset name (e.g., small-1x)
cpu	CPU allocation (vCPU)
memory	Memory allocation (GB)
centsPerMs	Cost per millisecond

ctx.batch

Property	Description
id	Batch ID (if run was triggered via batch)

Common Patterns

Checking Attempt Number

run: async (payload, { ctx }) => {
  if (ctx.attempt.number > 1) {
    console.log("This is a retry attempt");
  }
}

Environment-Specific Logic

run: async (payload, { ctx }) => {
  if (ctx.environment.type === "PRODUCTION") {
    await sendRealEmail(payload);
  } else {
    console.log("Skipping email in non-production environment");
  }
}

Logging with Run Context

run: async (payload, { ctx }) => {
  logger.info("Starting task", {
    runId: ctx.run.id,
    attempt: ctx.attempt.number,
    env: ctx.environment.type,
  });
}