# Scheduled Triggers

Schedule triggers to run workloads automatically on a recurring basis. Perfect for nightly training runs, batch predictions, data pipeline updates, or any workflow that needs to happen regularly.

## Why Schedule Your Workflows?

**Consistency:** Run training at the same time every day with fresh data

**Efficiency:** Launch batch jobs during off-peak hours to optimize costs

**Hands-free:** No manual intervention needed, just set it and forget it

**Flexibility:** Use simple recurring schedules or advanced cron expressions

***

## How Scheduling Works

Scheduled triggers require two components:

1. **Scheduled (Cron) condition:** Defines when the trigger fires
2. **Action:** Defines what to launch (execution, pipeline, etc.)

Scheduled triggers launch **no earlier than** the specified time and **no more frequently** than once per minute.

{% hint style="info" %}
If multiple conditions are added to a trigger, **all conditions must be met** at the same time for the trigger to launch.
{% endhint %}

***

## Quick Start Example

Let's create a simple scheduled execution that runs every weekday at noon UTC.

### Step 1: Add the Execution Step

Add this step to your `valohai.yaml`:

```yaml
- step:
    name: Scheduled Execution
    image: python:3.11
    command:
    - pip install valohai-utils
    - python ./scheduled.py
```

Create `scheduled.py`:

```python
import valohai
import datetime

valohai.prepare(
    step="Scheduled Execution",
)

month_day = datetime.datetime.now().strftime("%-d %b")

print(f"Today is {month_day}")
```

Commit and push these changes to Git, then fetch the new commit in Valohai.

### Step 2: Create the Trigger

1. Go to Project Settings → Triggers
2. Click **Create Trigger**
3. Set **Trigger Type** to "Scheduled" (default)
4. In the **Conditions** column, click **+ Add** → select **Scheduled (Cron)**
   * Select "On Weekdays"
   * Select "12:00"
5. In the **Actions** column, click **+ Add** → select **Run Execution**
   * **Source Commit Reference:** `main` (or your primary branch)
   * **Execution Step Name:** `Scheduled Execution`
   * **Execution Title:** `Daily execution at 12 UTC`
6. Click **Save Trigger**

The trigger will now launch automatically every weekday at noon UTC.

***

## Scheduling Options

### Simple Recurring Schedules

For common patterns, use the visual scheduler:

* **Daily** at a specific time
* **Weekdays only** (Monday–Friday)
* **Weekly** on specific days
* **Monthly** on specific dates

These are easy to configure and cover most use cases.

### Advanced Cron Expressions

For complex schedules, use cron syntax directly:

```
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6, Sunday = 0)
│ │ │ │ │
* * * * *
```

**Common cron patterns:**

| Pattern              | Cron Expression | Description                   |
| -------------------- | --------------- | ----------------------------- |
| Every hour           | `0 * * * *`     | On the hour, every hour       |
| Every 6 hours        | `0 */6 * * *`   | At 00:00, 06:00, 12:00, 18:00 |
| Every Monday at 9 AM | `0 9 * * 1`     | Weekly on Mondays             |
| First of the month   | `0 0 1 * *`     | Monthly at midnight           |
| Every 15 minutes     | `*/15 * * * *`  | Four times per hour           |

{% hint style="info" %}
Use [cronmaker.com](http://www.cronmaker.com/) to generate and validate complex cron expressions.
{% endhint %}

***

## Common Scheduling Patterns

### Pattern: Nightly Model Training

**Goal:** Retrain your model every night at 2 AM UTC with the latest data

```yaml
# valohai.yaml
- step:
    name: nightly-training
    image: pytorch/pytorch:2.0.0-cuda11.7-cudnn8-runtime
    command:
      - python train.py {parameters}
    inputs:
      - name: dataset
        default: datum://latest-training-data
```

**Trigger setup:**

* **Type:** Scheduled
* **Condition:** Cron `0 2 * * *` (daily at 2 AM)
* **Action:** Run execution `nightly-training`

***

### Pattern: Hourly Batch Predictions

**Goal:** Run inference on new data every hour

```yaml
# valohai.yaml
- pipeline:
    name: hourly-inference
    nodes:
      - name: fetch-new-data
        step: fetch-data
        type: execution
      - name: run-predictions
        step: predict
        type: execution
    edges:
      - [fetch-new-data.output.*, run-predictions.input.data]
```

**Trigger setup:**

* **Type:** Scheduled
* **Condition:** Cron `0 * * * *` (every hour on the hour)
* **Action:** Run pipeline `hourly-inference`

***

### Pattern: Weekly Performance Report

**Goal:** Generate model performance metrics every Monday morning

```yaml
# valohai.yaml
- step:
    name: weekly-report
    image: python:3.11
    command:
      - pip install -r requirements.txt
      - python generate_report.py
    outputs:
      - name: report.pdf
```

**Trigger setup:**

* **Type:** Scheduled
* **Condition:** Cron `0 9 * * 1` (Mondays at 9 AM)
* **Action:** Run execution `weekly-report`

***

## Monitoring and Debugging

### View Trigger Logs

Check if your scheduled triggers are firing correctly:

1. Go to Project Settings → Triggers
2. Find your trigger in the list
3. Click the **...** menu → **View Logs**

Logs show every trigger attempt, whether it succeeded or failed, and why.

### Common Issues

**Trigger not firing?**

* Check that the trigger is **Enabled** in the trigger settings
* Verify the cron expression is correct
* Ensure you have at least one condition set

**Trigger firing at wrong time?**

* All times in Valohai are **UTC**. Convert your local time to UTC.
* Use [time.is/UTC](https://time.is/UTC) to check current UTC time

**Multiple triggers firing at once?**

* This is normal for triggers with the same schedule
* Each trigger launches independently
* Consider consolidating into a single trigger if they should be coordinated

{% hint style="warning" %}
Triggers that repeatedly fail will auto-disable. Check logs and re-enable the trigger after fixing the issue.
{% endhint %}

***

## Next Steps

* **More trigger types?** Explore [Webhook Triggers](/automation-overview/triggers/webhooks.md) and [Notification Triggers](/automation-overview/triggers/notification-triggers.md)
* **Need custom logic?** Check out the [REST API](https://github.com/valohai/dokuhai/blob/main/docs/how-to/automation/triggers/scheduled/broken-reference/README.md)
* **Building complex workflows?** Learn about [Pipelines](/pipelines.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/automation-overview/triggers/scheduled-triggers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.