Scheduler Settings

The Settings → Scheduler tab holds the server-wide defaults that govern how Athena runs work in the background: the default command and deployment timeouts, how many jobs may run at once, how often dynamic collections refresh their members, how long job history, command history, and inactive agents are kept before automatic cleanup, and which mode the cron builder opens in. This page explains each setting, its default and allowed range, and how to read or change it from the console, the REST API, and PowerShell.

Where to find it#

Open Settings → Scheduler in the console. The tab groups the defaults into three sections, each described below:

• Execution Settings — default command timeout, default deployment timeout, and maximum concurrent jobs.
• Server Tasks — agent cleanup window, command history retention, and the dynamic collection refresh interval.
• History Settings — job execution history retention and the default cron builder mode. This section holds the Save button for the whole tab.

Execution settings#

The Execution Settings section configures the default execution parameters for scheduled jobs.

Server tasks#

The Server Tasks section configures settings for the housekeeping tasks that Athena runs on the server. Two of these values are consumed by built-in cleanup tasks, and one controls how often dynamic collection membership is recalculated.

History settings#

The History Settings section configures job execution history retention and the default mode the cron builder opens in. The tab's Save button lives in this section and commits every change made across all three sections.

REST API#

The same settings are available over the JWT-authenticated REST API on port 8443. Send the bearer token as Authorization: Bearer <token>; both endpoints require the Admin role.

# Read current scheduler settings
curl -k -H "Authorization: Bearer <token>" \
  https://athena.example.com:8443/api/settings/scheduler

# Update: 10-minute command timeout, 3-hour deployment timeout,
# keep job history 60 days, refresh collections every 10 minutes
curl -k -X PUT -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultCommandTimeoutMinutes": 10,
    "defaultDeploymentTimeoutMinutes": 180,
    "maxConcurrentJobs": 10,
    "historyRetentionDays": 60,
    "cleanupInactiveDays": 30,
    "collectionRefreshIntervalMinutes": 10,
    "commandRetentionDays": 30,
    "cronBuilderMode": "Visual"
  }' \
  https://athena.example.com:8443/api/settings/scheduler

Send the object you read back from GET with the fields you want to change — the update replaces the scheduler settings with the values you supply.

PowerShell#

The Athena PowerShell module reads and writes the scheduler settings with Get-AthenaSettings and Set-AthenaSettings using the Scheduler category. Sign in with Connect-Athena as an Admin first.

# Connect as an Admin
Connect-Athena -Server "athena.contoso.com"

# Read the current scheduler settings
$scheduler = Get-AthenaSettings -Category Scheduler
$scheduler.MaxConcurrentJobs
$scheduler.CollectionRefreshIntervalMinutes

# Keep job history for 60 days and refresh collections every 10 minutes
$scheduler.HistoryRetentionDays = 60
$scheduler.CollectionRefreshIntervalMinutes = 10
Set-AthenaSettings -Category Scheduler -Settings $scheduler

# Disable automatic dynamic-collection refresh
$scheduler.CollectionRefreshIntervalMinutes = 0
Set-AthenaSettings -Category Scheduler -Settings $scheduler

Set-AthenaSettings supports -WhatIf/-Confirm, so you can preview a change or gate it in a script.

Auditing#

Every change to the scheduler settings is written to the audit trail as a Scheduler settings change, recording the acting user, their IP address, and which values changed — for example a new deployment timeout or a change to the collection refresh interval. This gives you a complete record of who adjusted the background-work defaults and when.

Related#

• Scheduled Jobs — create and manage the recurring jobs these defaults apply to.
• Collections — dynamic collections refreshed on the interval set here.
• Software Deployment — deployments that use the default deployment timeout.
• Retiring & Removing Agents — how the inactive-agent cleanup window fits into agent lifecycle.
• General Settings — console-wide preferences on a neighbouring Settings tab.
• Roles & Permissions — the roles that govern who can change these settings.