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

# Cron Job Execution

> Execution history records for cron job runs including logs, output, and timing.

### Cron Job Execution

Cron Job Executions are historical records of each time a cron job runs. They capture the execution status, console logs, return values, timing information, and any errors that occurred.

#### At a Glance

* Records every scheduled and manual execution
* Captures console output and script return values
* Tracks execution duration and status
* Supports filtering by status and trigger type
* Useful for debugging and monitoring

#### Data Shape

```typescript theme={null}
// apps/azalt/src/server/db/types/cron-job.ts (simplified)
interface CronJobExecution {
  id: string;
  cronJobId: string;
  status: "running" | "success" | "failed" | "timeout";
  triggerType: "scheduled" | "manual";
  triggeredById: string | null;    // User ID for manual triggers
  startedAt: Date;
  finishedAt: Date | null;
  executionTimeMs: number | null;  // Duration in milliseconds
  logs: string | null;             // Console output
  error: string | null;            // Error message if failed
  output: JsonValue | null;        // Return value from script
}
```

#### Execution Status

| Status    | Description                       |
| --------- | --------------------------------- |
| `running` | Currently executing (in progress) |
| `success` | Completed without errors          |
| `failed`  | Terminated due to an error        |
| `timeout` | Exceeded 5-minute time limit      |

#### Trigger Types

| Type        | Description                      | `triggeredById` |
| ----------- | -------------------------------- | --------------- |
| `scheduled` | Automatic execution by scheduler | `null`          |
| `manual`    | User-initiated via UI or API     | User's ID       |

#### Logs and Output

**Console Logs**: All `console.log()`, `console.error()`, etc. calls are captured:

```javascript theme={null}
// In your cron job code
console.log('Starting data sync...');
console.log(`Processing ${items.length} items`);
console.error('Warning: API rate limit approaching');

// These appear in execution.logs as:
// [2024-01-15T10:30:00.000Z] Starting data sync...
// [2024-01-15T10:30:01.234Z] Processing 150 items
// [2024-01-15T10:30:02.567Z] Warning: API rate limit approaching
```

**Return Value**: The script's return value is stored in `output`:

```javascript theme={null}
// In your cron job code
const results = await processData();
return {
  processed: results.length,
  errors: results.filter(r => r.error).length,
  timestamp: new Date().toISOString()
};

// This object is stored in execution.output
```

#### Execution Statistics

The parent CronJob includes aggregated statistics from executions:

```typescript theme={null}
interface ExecutionStats {
  totalExecutions: number;      // All-time execution count
  successCount: number;         // Successful executions
  failedCount: number;          // Failed executions
  lastSuccess: Date | null;     // Most recent success
  lastFailure: Date | null;     // Most recent failure
  avgExecutionTimeMs: number | null;  // Average duration
}
```

#### Security & Permissions

* **View**: Any organization member can view execution history
* **Create**: System only (via scheduler or manual trigger)
* **Delete**: Not supported (audit trail preserved)

#### API Notes

* `cronJob.listExecutions`: Paginated list with filtering by status and trigger type
* `cronJob.getExecution`: Full execution details including logs and output
* `cronJob.get`: Includes recent executions and aggregated statistics

#### Monitoring Best Practices

1. **Check failure patterns**: Look for recurring errors at specific times
2. **Monitor execution duration**: Sudden increases may indicate issues
3. **Review logs regularly**: Catch warnings before they become failures
4. **Set up alerts**: Use the output to trigger external monitoring
5. **Track success rates**: Calculate `successCount / totalExecutions`

#### Example: Debugging a Failed Execution

```typescript theme={null}
// Get execution details via API
const execution = await api.cronJob.getExecution({ id: 'exec-123' });

// Check status and error
if (execution.status === 'failed') {
  console.log('Error:', execution.error);
  console.log('Logs:', execution.logs);
  console.log('Duration:', execution.executionTimeMs, 'ms');
}

// For timeout issues
if (execution.status === 'timeout') {
  console.log('Job exceeded 5-minute limit');
  console.log('Last logged output:', execution.logs);
}
```

#### Related Concepts

* CronJob - Parent scheduled automation job
* CronJobVariable - Environment variables and secrets