Skip to main content
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 -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 -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.