> ## 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 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](/concepts/tasks) and the [credentials](/concepts/credentials) to run it against. Each time the schedule fires, Deck creates one [task run](/concepts/task-runs) 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](https://console.deck.co), 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:

```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](/concepts/credentials#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](/concepts/task-runs) endpoint directly.

## Deep dives

<CardGroup cols={2}>
  <Card title="Automate task runs" icon="clock" href="/guides/triggers">
    Full examples with schedules, credential filters, skip conditions, and failure handling.
  </Card>

  <Card title="Task runs" icon="play" href="/concepts/task-runs">
    The execution primitive every trigger fire creates.
  </Card>

  <Card title="Credentials" icon="vault" href="/concepts/credentials">
    The credential lifecycle that drives enrollment in and out of a trigger.
  </Card>

  <Card title="Events" icon="bolt" href="/events/events">
    Subscribe to trigger lifecycle and trigger run events.
  </Card>
</CardGroup>
