> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Run a task or workflow on a schedule, fanned out across many credentials.

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](https://docs.deck.co/concepts/tasks.md) or a [workflow](https://docs.deck.co/concepts/workflows.md), and the [credentials](https://docs.deck.co/concepts/credentials.md) to run it against. Each time the schedule fires, Deck creates one [task run](https://docs.deck.co/concepts/task-runs.md), or one workflow run, per credential in scope.

A triggered run is identical to one you create with `POST /v2/tasks/{task_id}/run` or `POST /v2/workflows/{workflow_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 or one workflow, fixed at creation; to run a different one, create a new trigger. The task, or each step of the workflow, determines which agent does the work. Manage triggers through the API, or in the [Console](https://console.deck.co), where the Triggers page lists every trigger and each task or workflow shows its own, with enrolled credentials and recent fires.

## Schedules

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

```json theme={null}
{
  "type": "schedule",
  "cron": "0 6 * * *",
  "timezone": "America/New_York"
}
```

## 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](https://docs.deck.co/concepts/credentials.md#credential-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

| Status | Meaning |
| - | - |
| `active` | Firing on schedule |
| `inactive` | Configuration kept, nothing fires |

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](https://docs.deck.co/concepts/task-runs.md) endpoint directly.

## Deep dives

> [card] [Automate runs](https://docs.deck.co/guides/triggers.md)
>
> Full examples with schedules, credential filters, skip conditions, and failure handling.

> [card] [Task runs](https://docs.deck.co/concepts/task-runs.md)
>
> The execution primitive every trigger fire creates.

> [card] [Workflows](https://docs.deck.co/concepts/workflows.md)
>
> Chain tasks into one run, and schedule the whole chain with a trigger.

> [card] [Credentials](https://docs.deck.co/concepts/credentials.md)
>
> The credential lifecycle that drives enrollment in and out of a trigger.

> [card] [Events](https://docs.deck.co/events/events.md)
>
> Subscribe to trigger lifecycle and trigger run events.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.