# Scheduling Automations

Run your Streamline automations automatically on a schedule using cron expressions. Perfect for recurring tasks like daily reports, data synchronization, and monitoring.

## Overview

Streamline scheduling provides:

- **Cron Expressions**: Standard cron syntax for flexible scheduling
- **Timezone Support**: Run automations in any timezone
- **Enable/Disable**: Toggle schedules without deleting them
- **Next Run Time**: See when your automation will run next


## Setting a Schedule

### Using the CLI


```bash
# Schedule to run daily at 9 AM UTC
aitronos streamline schedule set <automation-id> \
  --cron "0 9 * * *" \
  --timezone "UTC"

# Schedule to run every hour
aitronos streamline schedule set <automation-id> \
  --cron "0 * * * *"

# Schedule to run every Monday at 8 AM EST
aitronos streamline schedule set <automation-id> \
  --cron "0 8 * * 1" \
  --timezone "America/New_York"
```

### Using the API


```bash
curl -X POST "https://api.aitronos.com/v1/streamline/automations/{automation_id}/schedule" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cron_expression": "0 9 * * *",
    "timezone": "UTC"
  }'
```

## Cron Expression Syntax

Cron expressions consist of 5 fields:


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

### Common Examples


```bash
# Every minute
* * * * *

# Every hour at minute 0
0 * * * *

# Every day at midnight
0 0 * * *

# Every day at 9 AM
0 9 * * *

# Every day at 9 AM and 5 PM
0 9,17 * * *

# Every weekday at 9 AM
0 9 * * 1-5

# Every Monday at 9 AM
0 9 * * 1

# First day of every month at midnight
0 0 1 * *

# Every 15 minutes
*/15 * * * *

# Every 6 hours
0 */6 * * *

# Every Sunday at 3 AM
0 3 * * 0
```

### Special Characters

- `*`: Any value
- `,`: Value list separator (e.g., `1,3,5`)
- `-`: Range of values (e.g., `1-5`)
- `/`: Step values (e.g., `*/15` = every 15 units)


## Timezone Support

Specify the timezone for your schedule:


```bash
# UTC (default)
--timezone "UTC"

# US Eastern Time
--timezone "America/New_York"

# US Pacific Time
--timezone "America/Los_Angeles"

# Central European Time
--timezone "Europe/Paris"

# Tokyo
--timezone "Asia/Tokyo"
```

### Finding Your Timezone

Use the [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format.

Common timezones:

- `UTC` - Coordinated Universal Time
- `America/New_York` - US Eastern
- `America/Chicago` - US Central
- `America/Denver` - US Mountain
- `America/Los_Angeles` - US Pacific
- `Europe/London` - UK
- `Europe/Paris` - Central European
- `Asia/Tokyo` - Japan
- `Australia/Sydney` - Australia


## Managing Schedules

### View Schedule


```bash
# Using CLI
aitronos streamline get <automation-id>

# Using API
curl "https://api.aitronos.com/v1/streamline/automations/{automation_id}" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN"
```

Response includes schedule information:


```json
{
  "id": "auto_abc123",
  "name": "My Automation",
  "schedule_enabled": true,
  "schedule_cron": "0 9 * * *",
  "schedule_timezone": "UTC",
  "schedule_next_run_at": "2025-11-28T09:00:00Z"
}
```

### Enable/Disable Schedule

Toggle the schedule without removing it:


```bash
# Disable schedule
curl -X POST "https://api.aitronos.com/v1/streamline/automations/{automation_id}/schedule/toggle" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Enable schedule
curl -X POST "https://api.aitronos.com/v1/streamline/automations/{automation_id}/schedule/toggle" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

### Update Schedule

To change the schedule, set a new one:


```bash
# Update to run every 2 hours
aitronos streamline schedule set <automation-id> \
  --cron "0 */2 * * *"
```

### Remove Schedule

Delete the schedule completely:


```bash
# Using CLI
aitronos streamline schedule remove <automation-id>

# Using API
curl -X DELETE "https://api.aitronos.com/v1/streamline/automations/{automation_id}/schedule" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN"
```

## Execution History

View scheduled execution history:


```bash
# List recent executions
aitronos streamline executions list <automation-id>

# Filter by trigger method
curl "https://api.aitronos.com/v1/streamline/automations/{automation_id}/executions?limit=50" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN"
```

Executions triggered by schedule have `trigger_method: "schedule"`.

## Best Practices

### 1. Use Appropriate Intervals

Don't schedule too frequently:


```bash
# ❌ Bad: Every minute (may hit rate limits)
* * * * *

# ✅ Good: Every 15 minutes
*/15 * * * *

# ✅ Good: Every hour
0 * * * *
```

### 2. Consider Timezone

Schedule in the appropriate timezone for your use case:


```bash
# For US business hours (9 AM EST)
aitronos streamline schedule set <automation-id> \
  --cron "0 9 * * 1-5" \
  --timezone "America/New_York"
```

### 3. Avoid Peak Hours

Distribute scheduled tasks to avoid peak times:


```bash
# Instead of everyone running at midnight
0 0 * * *

# Stagger executions
15 0 * * *  # 12:15 AM
30 0 * * *  # 12:30 AM
45 0 * * *  # 12:45 AM
```

### 4. Test Before Scheduling

Test your automation manually before setting a schedule:


```bash
# Test execution
aitronos streamline execute <automation-id>

# Verify results
aitronos streamline executions list <automation-id>

# If successful, set schedule
aitronos streamline schedule set <automation-id> --cron "0 9 * * *"
```

### 5. Monitor Scheduled Executions

Regularly check execution history:


```bash
# View recent executions
aitronos streamline executions list <automation-id> --limit 10

# Check for failures
curl "https://api.aitronos.com/v1/streamline/automations/{automation_id}/executions" \
  -H "Authorization: Bearer $FREDDY_SESSION_TOKEN" \
  | jq '.executions[] | select(.status == "failed")'
```

### 6. Handle Failures Gracefully

Implement error handling in your automation:


```python
def main(**kwargs):
    """Automation with error handling."""
    try:
        # Your logic here
        result = process_data()
        return {"success": True, "data": result}
    except Exception as e:
        # Log error
        print(f"Error: {e}")
        # Return error status
        return {"success": False, "error": str(e)}
```

## Use Cases

### Daily Reports


```bash
# Generate report every day at 8 AM
aitronos streamline schedule set <automation-id> \
  --cron "0 8 * * *" \
  --timezone "America/New_York"
```

### Data Synchronization


```bash
# Sync data every 4 hours
aitronos streamline schedule set <automation-id> \
  --cron "0 */4 * * *"
```

### Weekly Cleanup


```bash
# Clean up old data every Sunday at 2 AM
aitronos streamline schedule set <automation-id> \
  --cron "0 2 * * 0"
```

### Business Hours Monitoring


```bash
# Check system status every 30 minutes during business hours (9 AM - 5 PM, Mon-Fri)
# Note: Requires multiple schedules or custom logic
aitronos streamline schedule set <automation-id> \
  --cron "*/30 9-17 * * 1-5" \
  --timezone "America/New_York"
```

### Monthly Reports


```bash
# Generate monthly report on the 1st at 9 AM
aitronos streamline schedule set <automation-id> \
  --cron "0 9 1 * *"
```

## Troubleshooting

### Schedule Not Running

**Check schedule status:**


```bash
aitronos streamline get <automation-id>
```

Verify:

- `schedule_enabled` is `true`
- `schedule_cron` is correct
- `schedule_next_run_at` is in the future


**Common issues:**

- Schedule is disabled
- Invalid cron expression
- Automation is inactive
- Timezone mismatch


### Wrong Execution Time

**Verify timezone:**


```bash
# Check current schedule
aitronos streamline get <automation-id>

# Update timezone if needed
aitronos streamline schedule set <automation-id> \
  --cron "0 9 * * *" \
  --timezone "America/New_York"
```

### Execution Failed

**Check execution logs:**


```bash
# Get recent executions
aitronos streamline executions list <automation-id>

# Get specific execution details
aitronos streamline executions get <execution-id>
```

**Common issues:**

- Automation code errors
- Missing dependencies
- Timeout (default 5 minutes)
- Resource limits exceeded


## Cron Expression Tools

### Online Generators

- [Crontab Guru](https://crontab.guru/) - Interactive cron expression editor
- [Cron Expression Generator](https://www.freeformatter.com/cron-expression-generator-quartz.html)


### Validation

Test your cron expression before setting:


```bash
# Use crontab.guru
https://crontab.guru/#0_9_*_*_*

# Or use Python
python3 -c "from croniter import croniter; print(croniter.is_valid('0 9 * * *'))"
```

## Next Steps

- **[Parameters & Configuration](/docs/documentation/streamline/parameters)** - Pass parameters to scheduled executions
- **[Monitoring](/docs/documentation/streamline/monitoring)** - Monitor scheduled automation performance
- **[Best Practices](/docs/documentation/streamline/best-practices)** - Follow recommended patterns


## Support

Need help with scheduling?

- **Email**: support@aitronos.com
- **Documentation**: [Streamline Overview](/docs/documentation/streamline/overview)
- **API Reference**: [Scheduling API](/docs/api-reference/streamline/automations-set-schedule)