Skip to main content
Say you fetch a monthly bill for 10,000 connected utility accounts. Without triggers, you build the orchestration yourself: a daily cron that queries active credentials, fans out a task run to each, skips the accounts already billed this month, and sidelines the ones with expired passwords. A trigger moves all of that into Deck. Declare “run this task every day at 6am against every credential on this source,” and Deck handles the scheduling, fan-out, skip logic, and observability.

​
How triggers fit in

A trigger ties a schedule to a task and the credentials to run it against. Each time the schedule fires, Deck creates one task run per credential in scope. A triggered run is identical to one you create with POST /v2/tasks/{task_id}/run, with the same lifecycle, statuses, artifacts, and events. The only difference is the initiator, recorded as a trigger_id on the run. A trigger targets one task, fixed at creation; to run a different task, create a new trigger. The task determines which agent does the work. Manage triggers through the API, or from the task’s detail page in the Console, where each task shows its triggers, their enrolled credentials, and recent fires.

​
Schedules

A trigger fires on a cron schedule, evaluated in the timezone you specify:

​
Credential scope

A trigger targets credentials one of two ways:
  • credential_ids, an explicit list. The set is exactly the credentials you name, one or many, until you edit the trigger.
  • credential_filter, a scope resolved each time the trigger fires: credentials on the listed sources (or on every source, with "source_ids": ["*"]) with the listed statuses. Enrollment is dynamic. Connect a 10,001st user and that credential gets runs on the next fire, no registration step.
A credential that goes invalid drops out of a filter on its own (or is skipped in an explicit list), and resumes automatically once the user re-authenticates. The trigger keeps running for everyone else.

​
Skip conditions

skip_if is evaluated per credential before a run is created. If the credential’s most recent run of the task already succeeded within a time window, it’s skipped this time and no run is created. A bill fetched today doesn’t need re-fetching tomorrow, so a daily schedule with a 25-day success window does a handful of real runs per credential per cycle instead of thirty.

​
Trigger statuses

Toggle between them with PATCH /v2/triggers/{trigger_id}. There are no separate pause and resume endpoints.

​
When to use triggers

If you’re running a cron against the Deck API, iterating your own credential list, and tracking which users already ran this month, that’s a trigger. Define it once and let Deck run it. If you need a task to run right now for one user, call the task run endpoint directly.

​
Deep dives

Automate task runs

Full examples with schedules, credential filters, skip conditions, and failure handling.

Task runs

The execution primitive every trigger fire creates.

Credentials

The credential lifecycle that drives enrollment in and out of a trigger.

Events

Subscribe to trigger lifecycle and trigger run events.