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

# Scheduled Actions

> Understand how Thread schedules and executes delayed actions automatically

## Scheduled Actions Overview

Scheduled actions are actions with `delay_hours > 0` that execute at a future time. Thread's scheduling system ensures actions trigger at the perfect moment without manual intervention.

***

## How Scheduling Works

### The Scheduling Pipeline

<Steps>
  <Step title="Milestone Starts">
    CSM starts a milestone → status changes to "in\_progress"
  </Step>

  <Step title="Actions Scanned">
    Thread scans all actions in milestone for triggers
  </Step>

  <Step title="Immediate Actions">
    Actions with `delay_hours: 0` execute immediately
  </Step>

  <Step title="Delayed Actions Scheduled">
    Actions with delays added to `scheduled_action_executions` table

    **Calculation:**

    ```
    execution_time = milestone_start_time + delay_hours
    ```

    **Example:**

    ```
    Milestone started: 2024-03-15 10:00 AM
    Action delay: 48 hours
    Scheduled execution: 2024-03-17 10:00 AM
    ```
  </Step>

  <Step title="Cron Job Monitors">
    Hourly cron job checks for actions ready to execute
  </Step>

  <Step title="Execution Triggered">
    When current time ≥ execution\_time:

    * AI generates draft
    * Action moves to "ready" status
    * Appears in CSM Implementation Tab
  </Step>
</Steps>

***

## Configuration

### Setting Delays in Templates

When creating actions:

```typescript theme={null}
{
  trigger: {
    type: "milestone_start",
    delay_hours: 48  // 2 days
  }
}
```

**Common delay values:**

| Hours | Duration  | Use Cases                              |
| ----- | --------- | -------------------------------------- |
| 0     | Immediate | Welcome emails, announcements          |
| 24    | 1 day     | Follow-ups, reminders                  |
| 48    | 2 days    | Secondary actions, non-urgent requests |
| 72    | 3 days    | Giving customers breathing room        |
| 168   | 1 week    | Long-lead items, reviews               |
| 720   | 30 days   | Post-launch check-ins                  |

### Changing Delays After Creation

CSMs can adjust delays for specific accounts:

1. Navigate to Implementation Tab
2. Find scheduled action (status: "pending")
3. Click "Reschedule"
4. Enter new delay\_hours or specific date/time
5. Save changes

<Info>
  Rescheduling only affects this specific account. Template delays remain unchanged for future accounts.
</Info>

***

## Viewing Scheduled Actions

### Per-Account View

In Implementation Tab:

**Pending actions show:**

* Action label
* Scheduled execution date/time
* Days/hours until execution
* Option to reschedule or execute immediately

### Organization-Wide View

**(Admin only)**

Navigate to **Settings** → **Scheduled Actions**

**See:**

* All scheduled actions across accounts
* Execution times
* Associated accounts and milestones
* Option to manually trigger or cancel

***

## The Cron System

### How the Cron Job Works

**Frequency:** Runs every hour (configurable)

**Process:**

1. Query `scheduled_action_executions` table
2. Filter for `execution_time ≤ current_time` AND `status = pending`
3. For each action:
   * Generate AI draft (if applicable)
   * Update action status to "ready"
   * Notify CSM (optional)
   * Remove from scheduled queue
4. Log execution results

**Cron endpoint:** `/api/cron/execute-scheduled`

**Security:** Protected by `CRON_SECRET` environment variable

<Warning>
  The cron job uses the admin client to bypass RLS. This is necessary for system-level operations but must be kept secure.
</Warning>

### Cron Schedule

Configured in `vercel.json`:

```json theme={null}
{
  "crons": [
    {
      "path": "/api/cron/execute-scheduled",
      "schedule": "0 * * * *"
    }
  ]
}
```

**Schedule format:** Standard cron syntax

* `0 * * * *` = Every hour at :00
* `0 */4 * * *` = Every 4 hours
* `0 0 * * *` = Daily at midnight

***

## Timing Precision

### Execution Timing Expectations

**How precise is scheduling?**

<Tabs>
  <Tab title="Same-Hour (✅)">
    Actions scheduled for 2:00 PM will execute between 2:00-2:59 PM

    **Guarantee:** Within same hour as scheduled
  </Tab>

  <Tab title="Not Minute-Exact (❌)">
    Don't expect execution at exactly 2:00:00 PM

    **Why:** Cron runs hourly, not by-the-minute
  </Tab>

  <Tab title="Order Preserved (✅)">
    If multiple actions scheduled for same hour, they execute in order

    **Example:**

    * Action A: 2:15 PM
    * Action B: 2:45 PM
    * Both execute 2:00-2:59 PM, A before B
  </Tab>
</Tabs>

<Info>
  For most use cases, hourly precision is sufficient. If you need minute-exact timing, execute actions manually at the desired time.
</Info>

***

## Common Scheduling Patterns

### Onboarding Email Sequence

```
Day 0 (Kickoff starts):
├── Welcome Email (immediate)
└── Portal Introduction (immediate)

Day 1:
└── Pre-Kickoff Form (24hr delay)

Day 3:
└── Kickoff Meeting Reminder (72hr delay)

Day 7:
└── Week 1 Progress Update (168hr delay)

Day 14:
└── Mid-Implementation Check-in (336hr delay)
```

### Multi-Touch Follow-Up

```
Action 1: Initial Email (immediate)
Action 2: Follow-up if no response (48hr delay)
Action 3: Final reminder (96hr delay)
Action 4: CSM manual outreach (manual trigger if still no response)
```

### Post-Launch Sequence

```
Launch Day: Go-Live Email (immediate)
Day 1: Post-Launch Check-in (24hr delay)
Day 7: Week 1 Review (168hr delay)
Day 30: Monthly Success Review (720hr delay)
Day 90: Quarterly Business Review (2160hr delay)
```

***

## Managing Scheduled Actions

### Rescheduling Actions

**When to reschedule:**

* Customer requested delay
* Holiday or blackout period
* Dependency not met
* Customer capacity issues

**How to reschedule:**

1. Go to Implementation Tab
2. Find pending action
3. Click "Reschedule"
4. Choose:
   * New delay\_hours from milestone start
   * Specific date/time
5. Save

<Tip>
  If you reschedule multiple related actions, maintain their relative spacing (e.g., if they were 48 hours apart, keep them 48 hours apart in new schedule).
</Tip>

### Executing Early

**When to execute early:**

* Customer ready before scheduled time
* Blocking progress
* Customer explicitly requested

**How:**

1. Navigate to pending action
2. Click "Execute Now"
3. Action immediately generates draft and moves to "ready"
4. Review and execute as normal

<Warning>
  Executing early removes it from the scheduled queue. It won't execute again at the originally scheduled time.
</Warning>

### Canceling Scheduled Actions

**When to cancel:**

* Action no longer needed
* Replaced by different action
* Customer no longer requires this

**How:**

1. Find pending action
2. Click "Cancel"
3. Confirm cancellation
4. Action removed from queue (can't be undone)

***

## Troubleshooting

### "Scheduled Action Didn't Trigger"

**Problem:** Past scheduled time but action still pending

**Possible causes:**

1. Cron job hasn't run yet (runs hourly)
2. Cron job failed (check logs)
3. Account or milestone was deleted
4. Action was manually canceled

**Solutions:**

* Wait for next hour's cron run
* Check cron logs in Vercel
* Manually execute if urgent
* Contact support if persistent

### "Action Triggered Too Early/Late"

**Problem:** Execution time doesn't match expectations

**Possible causes:**

1. Milestone start time different than expected
2. Action was manually rescheduled
3. Timezone confusion
4. Delay calculation error

**Solutions:**

* Verify milestone started at expected time
* Check action history for reschedules
* Confirm timezone settings
* Recalculate: milestone\_start + delay\_hours

### "Multiple Actions Triggered at Once"

**Problem:** Several actions executed simultaneously, overwhelming customer

**Possible causes:**

1. Multiple actions scheduled for same time
2. Milestone started late, backlog of actions triggered
3. Cron job backlog processed all at once

**Solutions:**

* Stagger action delays in template (avoid same delay\_hours)
* If milestone delayed, reschedule future actions before starting
* Space actions 24-48 hours apart minimum

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Space Actions Out" icon="calendar-days">
    Use 24-72 hour spacing between actions to avoid overwhelming customers
  </Card>

  <Card title="Consider Timezones" icon="globe">
    Schedule considering customer timezone (9 AM their time, not yours)
  </Card>

  <Card title="Plan for Delays" icon="clock">
    Expect customers to be slower than template estimates—add buffer
  </Card>

  <Card title="Monitor Pending Queue" icon="list">
    Regularly review scheduled actions to catch issues early
  </Card>

  <Card title="Test Timing" icon="flask">
    Use test accounts to verify delay calculations work as expected
  </Card>

  <Card title="Document Patterns" icon="book">
    Track which delay patterns work best for your customer segments
  </Card>
</CardGroup>

***

## Advanced Scheduling

### Conditional Delays

**(Future feature)**

Adjust delays based on customer attributes:

```typescript theme={null}
{
  trigger: {
    type: "milestone_start",
    delay_hours: customer.segment === "enterprise" ? 72 : 24
  }
}
```

**Use cases:**

* Longer delays for enterprise (more stakeholders)
* Shorter delays for SMB (faster decision-making)
* Industry-specific timing (healthcare compliance reviews)

### Business Day Scheduling

**(Future feature)**

Skip weekends and holidays:

```typescript theme={null}
{
  trigger: {
    type: "milestone_start",
    delay_hours: 48,
    business_days_only: true
  }
}
```

**Example:**

* Friday 3 PM + 24 business hours = Tuesday 3 PM (not Saturday)

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Action Execution" icon="bolt" href="/csm-guide/automation/action-execution">
    Learn how actions trigger and execute
  </Card>

  <Card title="AI Generation" icon="robot" href="/csm-guide/automation/ai-generation">
    Understand AI-powered draft creation
  </Card>

  <Card title="Template Design" icon="palette" href="/csm-guide/templates/creating-templates">
    Design templates with effective delays
  </Card>

  <Card title="Best Practices" icon="star" href="/csm-guide/templates/best-practices">
    Learn proven scheduling patterns
  </Card>
</CardGroup>