Trigger.dev Vocabulary

vocabulary:
  name: Trigger.dev Vocabulary
  description: >-
    Domain vocabulary for the Trigger.dev background job and workflow automation
    platform. Covers task execution, scheduling, queue management, deployment
    lifecycle, and human-in-the-loop workflow patterns.
  version: "1.1.0"
  created: "2026-05-03"
  modified: "2026-05-22"

domains:
  - name: Task Execution
    description: Core concepts for defining and running background tasks
    terms:
      - term: Task
        definition: The fundamental unit of work in Trigger.dev, defined as a TypeScript export using the task() function
        synonyms: [background job, worker, handler]
      - term: Task Identifier
        definition: A unique string identifier for a task (kebab-case by convention, e.g., process-payment)
        synonyms: [taskId, task name, task key]
      - term: Run
        definition: A single execution instance of a task, created when the task is triggered
        synonyms: [execution, job run, task run, invocation]
      - term: Run ID
        definition: A unique identifier for a specific run, prefixed with run_ (e.g., run_abc123)
        synonyms: [runId, execution ID, job ID]
      - term: Payload
        definition: The JSON data passed to a task when it is triggered, accessible as the first argument of task.run()
        synonyms: [input, job data, trigger payload]
      - term: Output
        definition: The value returned by task.run() upon successful completion
        synonyms: [result, return value, task result]
      - term: Attempt
        definition: A single execution attempt of a run (multiple attempts occur on retry after failure)
        synonyms: [execution attempt, retry attempt]

  - name: Run Lifecycle
    description: Status states and lifecycle events for task runs
    terms:
      - term: QUEUED
        definition: The run is waiting to be picked up by a worker
        synonyms: [pending, waiting, enqueued]
      - term: EXECUTING
        definition: The run is actively being processed by a worker
        synonyms: [running, processing, in-progress]
      - term: COMPLETED_SUCCESSFULLY
        definition: The run finished and task.run() returned a value without throwing
        synonyms: [succeeded, completed, done]
      - term: COMPLETED_WITH_ERRORS
        definition: The run finished but task.run() threw an error or returned an error result
        synonyms: [failed, error]
      - term: REATTEMPTING
        definition: The run failed and is waiting to be retried based on retry configuration
        synonyms: [retrying, awaiting retry]
      - term: WAITING_TO_RESUME
        definition: The run is paused at a wait point (wait.for, wait.until, or waitpoint token)
        synonyms: [paused, suspended, waiting]
      - term: CANCELLED
        definition: The run was manually cancelled via the API or dashboard
        synonyms: [stopped, aborted]
      - term: DELAYED
        definition: The run was triggered with a delay and is waiting for its scheduled execution time
        synonyms: [scheduled, deferred]

  - name: Scheduling
    description: Concepts for recurring and time-based task execution
    terms:
      - term: Schedule
        definition: A configuration that triggers a task automatically on a recurring basis using a cron expression
        synonyms: [cron job, scheduled task, recurring job]
      - term: Schedule ID
        definition: Unique identifier for a schedule, prefixed with sched_
        synonyms: [scheduleId, schedule identifier]
      - term: CRON Expression
        definition: A string in cron format specifying when a task should run (e.g., 0 9 * * MON-FRI)
        synonyms: [cron, cron string, schedule expression]
      - term: IMPERATIVE Schedule
        definition: A schedule created via the Management API (as opposed to defined in code)
        synonyms: [dynamic schedule, API-created schedule]
      - term: Deduplication Key
        definition: A key that prevents creating duplicate schedules with the same configuration
        synonyms: [deduplicationKey, idempotency key for schedules]
      - term: External ID
        definition: A custom identifier linking a Trigger.dev schedule to an external system record
        synonyms: [externalId, customer ID, external reference]

  - name: Queue Management
    description: Concepts for controlling task execution concurrency and flow
    terms:
      - term: Queue
        definition: A named buffer that controls the order and concurrency of task runs
        synonyms: [task queue, job queue, work queue]
      - term: Concurrency Limit
        definition: The maximum number of runs that can execute simultaneously in a queue
        synonyms: [concurrencyLimit, max concurrent, parallelism limit]
      - term: Queue Depth
        definition: The number of runs currently waiting in a queue to be executed
        synonyms: [depth, queue length, backlog]
      - term: Concurrency Key
        definition: A dynamic key that scopes concurrency limits (e.g., per-tenant isolation)
        synonyms: [concurrencyKey, scope key, isolation key]

  - name: Deployments
    description: Concepts for managing task code deployments
    terms:
      - term: Deployment
        definition: A versioned snapshot of task code pushed to Trigger.dev Cloud or a self-hosted instance
        synonyms: [version, release, code deployment]
      - term: Deployment Version
        definition: A semantic version string assigned to each deployment (e.g., 20260503.1)
        synonyms: [version string, build version]
      - term: Promote
        definition: The act of making a specific deployment version the active version for production traffic
        synonyms: [promote to production, activate version]

  - name: Workflow Patterns
    description: Advanced workflow orchestration patterns
    terms:
      - term: Batch
        definition: A group of multiple task runs triggered together in a single API call
        synonyms: [batch run, bulk trigger, parallel batch]
      - term: Waitpoint
        definition: A pause point within a run that suspends execution until an external condition is met
        synonyms: [wait token, pause point, checkpoint]
      - term: Waitpoint Token
        definition: A unique token created to represent a waitpoint that can be completed externally
        synonyms: [wait token, approval token, human-in-the-loop token]
      - term: Human-in-the-Loop
        definition: A workflow pattern where execution pauses for human input or approval via a waitpoint token
        synonyms: [HITL, approval workflow, manual review step]
      - term: Child Task
        definition: A task triggered from within another task using triggerAndWait() or trigger()
        synonyms: [subtask, nested task, child run]
      - term: Idempotency Key
        definition: A unique key that prevents duplicate runs when the same request is submitted multiple times
        synonyms: [idempotencyKey, dedup key, request deduplication]

  - name: Authentication
    description: API authentication concepts
    terms:
      - term: Secret Key
        definition: >-
          An API key for server-side authentication, prefixed by environment:
          tr_dev_ (development), tr_prod_ (production), tr_stg_ (staging).
          Set as TRIGGER_SECRET_KEY environment variable.
        synonyms: [secret API key, TRIGGER_SECRET_KEY, bearer token]
      - term: Personal Access Token
        definition: User-scoped token (prefix tr_pat_) granting access to every org, project, and environment
          the user belongs to. Requires projectRef when calling project-scoped endpoints.
        synonyms: [PAT, tr_pat_, user token]
      - term: Environment
        definition: An isolated deployment context (Development, Staging, Production) with separate runs and configuration
        synonyms: [env, deployment environment]
      - term: Preview Branch
        definition: A per-branch deployment environment selected via the x-trigger-branch header or the
          previewBranch SDK option. Only applicable to the preview environment.
        synonyms: [preview environment, branch deployment]

  - name: Realtime and Streaming
    description: Concepts for live run subscriptions and typed streams
    terms:
      - term: Realtime Run
        definition: A subscription to the live state of a single run, surfaced via the useRealtimeRun
          React hook or backend subscribeToRun method.
        synonyms: [live run, subscription]
      - term: Realtime Stream
        definition: A typed data stream emitted from a running task and consumed by clients via
          useRealtimeStream or backend stream APIs.
        synonyms: [task stream, output stream]
      - term: Input Stream
        definition: Bidirectional typed data channel allowing clients to send data into a running task.
        synonyms: [task input channel]
      - term: Wait Token Hook
        definition: The useWaitToken React hook that resolves when a waitpoint token is completed.
        synonyms: [useWaitToken, approval hook]

  - name: Query and Observability
    description: Concepts for analyzing run data and dashboards
    terms:
      - term: TRQL
        definition: Trigger.dev's query language for analyzing runs, tasks, and metrics. Executed via
          POST /api/v1/query with environment, project, or organization scope.
        synonyms: [Trigger Query Language, query]
      - term: Dashboard
        definition: A saved set of TRQL queries rendered as charts and tables in the Trigger.dev UI.
        synonyms: [analytics dashboard, observability board]
      - term: Run Event
        definition: An OpenTelemetry span emitted during run execution. Includes level, kind, duration,
          and nested events.
        synonyms: [span, trace event, log event]
      - term: Run Trace
        definition: The full distributed trace tree for a run, including all child runs and their spans.
        synonyms: [distributed trace, run tree]
      - term: Replay Detection
        definition: The ctx.run.isReplay flag indicating a task is executing as a replay of a prior run.
        synonyms: [replay flag, isReplay]