Scheduler API

Monitor and control scheduled background tasks

All scheduler endpoints require admin role. Unauthorized users will receive a 403 Forbidden response.

Overview

The Scheduler API provides visibility into Mission Control’s background task system. The scheduler runs several automated maintenance tasks:

• Auto Backup - Daily database backups at 3:00 AM UTC
• Auto Cleanup - Daily data pruning at 4:00 AM UTC based on retention policies
• Agent Heartbeat - Agent liveness checks every 5 minutes
• Webhook Retry - Failed webhook delivery retries every 60 seconds
• Claude Session Scan - Active session monitoring every 60 seconds

Get Scheduler Status

Returns the current state of all scheduled tasks including next run times and last execution results.

cURL

curl -X GET https://your-domain.com/api/scheduler \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN"

Response

tasks · array

Array of scheduled task status objects

id · string · required

Task identifier (auto_backup, auto_cleanup, agent_heartbeat, webhook_retry, claude_session_scan)

name · string · required

Human-readable task name

enabled · boolean · required

Whether the task is currently enabled (controlled via settings)

lastRun · integer

Unix timestamp (milliseconds) of last execution, or null if never run

nextRun · integer · required

Unix timestamp (milliseconds) of next scheduled execution

running · boolean · required

Whether the task is currently executing

lastResult · object

Result of the most recent execution

ok · boolean · required

Whether the task succeeded

message · string · required

Result message (e.g., “Backup created (2048KB)” or error details)

timestamp · integer · required

When this result was generated (milliseconds)

Example Response

{
  "tasks": [
    {
      "id": "auto_backup",
      "name": "Auto Backup",
      "enabled": true,
      "lastRun": 1709524800000,
      "nextRun": 1709611200000,
      "running": false,
      "lastResult": {
        "ok": true,
        "message": "Backup created (2048KB)",
        "timestamp": 1709524800000
      }
    },
    {
      "id": "agent_heartbeat",
      "name": "Agent Heartbeat Check",
      "enabled": true,
      "lastRun": 1709524500000,
      "nextRun": 1709524800000,
      "running": false,
      "lastResult": {
        "ok": true,
        "message": "All agents healthy",
        "timestamp": 1709524500000
      }
    }
  ]
}

Trigger Scheduled Task

Manually execute a scheduled task immediately, bypassing the normal schedule. Useful for testing or running on-demand backups.

cURL

curl -X POST https://your-domain.com/api/scheduler \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "auto_backup"}'

Request Body

task_id · string · required

Task to trigger. Must be one of:

• auto_backup - Create database backup immediately
• auto_cleanup - Run data cleanup based on retention policies
• agent_heartbeat - Check agent liveness and mark stale agents offline

Response

ok · boolean · required

Whether the task executed successfully

message · string · required

Result message with execution details or error information

Example Responses

Successful Backup

{
  "ok": true,
  "message": "Backup created (2048KB)"
}

Cleanup Result

{
  "ok": true,
  "message": "Cleaned 342 stale records"
}

Heartbeat Check

{
  "ok": true,
  "message": "Marked 2 agent(s) offline: agent-alpha, agent-beta"
}

Cron Configuration

Backup Schedule

• Frequency: Daily at 3:00 AM UTC
• Interval: 24 hours
• Control Setting: general.auto_backup (boolean)
• Retention: Keeps last N backups (configured via general.backup_retention_count)

Cleanup Schedule

• Frequency: Daily at 4:00 AM UTC
• Interval: 24 hours
• Control Setting: general.auto_cleanup (boolean)
• Target Tables: activities, audit_log, notifications, pipeline_runs, token_usage
• Retention Policies: Configured per table via retention.* settings

Agent Heartbeat

• Frequency: Every 5 minutes
• Control Setting: general.agent_heartbeat (default: enabled)
• Timeout: Configurable via general.agent_timeout_minutes (default: 10)
• Action: Marks agents offline if no heartbeat received within timeout period

Webhook Retry

• Frequency: Every 60 seconds
• Control Setting: webhooks.retry_enabled (default: enabled)
• Purpose: Retry failed webhook deliveries with exponential backoff

Claude Session Scan

• Frequency: Every 60 seconds
• Control Setting: general.claude_session_scan (default: enabled)
• Purpose: Monitor and sync active Claude Desktop sessions

Enabling/Disabling Tasks

Tasks are controlled via the Settings API. Use the settings keys listed in each task’s “Control Setting” field.

# Enable auto backup
curl -X PUT https://your-domain.com/api/settings \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"general.auto_backup": "true"}}'

# Disable auto cleanup
curl -X PUT https://your-domain.com/api/settings \
  -H "Cookie: mc-session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"general.auto_cleanup": "false"}}'

Error Responses

400 Bad Request

Invalid task_id provided. Must be one of: auto_backup, auto_cleanup, agent_heartbeat

401 Unauthorized

User is not authenticated. Check session cookie.

403 Forbidden

User does not have admin role. Only admins can control the scheduler.

500 Internal Server Error

Task execution failed. Check the response message for error details.