Skip to main content
Version: v1.0+

Scheduled Tasks

Manage automated server tasks including backups, restarts, command execution, and custom schedules.

List Schedules

Retrieve all scheduled tasks for a server.

GET /api/client/servers/{server}/schedules

URL Parameters

ParameterTypeDescription
serverstringServer identifier (UUID or short ID)

Example Request

GET /api/client/servers/{server}/schedules
curl "https://your-panel.com/api/client/servers/d3aac109/schedules" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Get Schedule Details

Retrieve detailed information about a specific schedule including all tasks.

GET /api/client/servers/{server}/schedules/{schedule}

URL Parameters

ParameterTypeDescription
serverstringServer identifier (UUID or short ID)
scheduleintegerSchedule ID

Example Request

curl "https://your-panel.com/api/client/servers/d3aac109/schedules/2" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Create Schedule

Create a new scheduled task for the server.

POST /api/client/servers/{server}/schedules

Request Body

FieldTypeRequiredDescription
namestringYesSchedule name (max 255 characters)
minutestringYesCron minute (0-59 or *)
hourstringYesCron hour (0-23 or *)
day_of_monthstringYesCron day of month (1-31 or *)
monthstringYesCron month (1-12 or *)
day_of_weekstringYesCron day of week (0-6 or *)
is_activebooleanNoEnable schedule immediately (default: true)
only_when_onlinebooleanNoOnly run when server is online (default: false)

Example Request

curl -X POST "https://your-panel.com/api/client/servers/d3aac109/schedules" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"name": "Daily Backup",
"minute": "0",
"hour": "3",
"day_of_month": "*",
"month": "*",
"day_of_week": "*",
"is_active": true,
"only_when_online": false
}'

Success Response

{
"object": "server_schedule",
"attributes": {
"id": 12,
"name": "Daily Backup",
"cron": {
"day_of_week": "*",
"day_of_month": "*",
"hour": "3",
"minute": "0",
"month": "*"
},
"is_active": true,
"is_processing": false,
"only_when_online": false,
"last_run_at": null,
"next_run_at": "2023-10-21T03:00:00+00:00",
"created_at": "2023-10-20T16:45:00+00:00",
"updated_at": "2023-10-20T16:45:00+00:00",
"relationships": {
"tasks": {
"object": "list",
"data": []
}
}
}
}

Cron Expression Examples

ScheduleMinuteHourDay MonthMonthDay WeekDescription
Every hour0****Run at minute 0 of every hour
Daily at 3 AM03***Run daily at 3:00 AM
Weekly on Sunday02**0Run Sundays at 2:00 AM
Monthly on 1st3041**Run 1st of month at 4:30 AM
Every 15 minutes*/15****Run every 15 minutes
Weekdays only08**1-5Run weekdays at 8:00 AM

Error Responses

Schedule Limit Reached (400)

{
"errors": [
{
"code": "TooManySchedulesException",
"status": "400",
"detail": "This server has reached its schedule limit."
}
]
}

Invalid Cron Expression (422)

{
"errors": [
{
"code": "ValidationException",
"status": "422",
"detail": "The provided cron expression is invalid.",
"meta": {
"rule": "cron_expression",
"source_field": "minute"
}
}
]
}

Update Schedule

Modify an existing schedule's configuration.

POST /api/client/servers/{server}/schedules/{schedule}

URL Parameters

ParameterTypeDescription
serverstringServer identifier (UUID or short ID)
scheduleintegerSchedule ID

Request Body

FieldTypeRequiredDescription
namestringNoSchedule name
minutestringNoCron minute
hourstringNoCron hour
day_of_monthstringNoCron day of month
monthstringNoCron month
day_of_weekstringNoCron day of week
is_activebooleanNoEnable/disable schedule
only_when_onlinebooleanNoOnly run when server is online

Example Request

curl -X POST "https://your-panel.com/api/client/servers/d3aac109/schedules/12" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Daily Backup",
"hour": "2",
"is_active": false
}'

Success Response (204)

Returns empty response body with status code 204.


Delete Schedule

Permanently delete a schedule and all its tasks.

DELETE /api/client/servers/{server}/schedules/{schedule}

URL Parameters

ParameterTypeDescription
serverstringServer identifier (UUID or short ID)
scheduleintegerSchedule ID

Example Request

curl -X DELETE "https://your-panel.com/api/client/servers/d3aac109/schedules/12" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Success Response (204)

Returns empty response body with status code 204.

Warning

Schedule deletion is permanent and irreversible. All associated tasks will also be deleted.


Execute Schedule

Manually trigger a schedule to run immediately.

POST /api/client/servers/{server}/schedules/{schedule}/execute

URL Parameters

ParameterTypeDescription
serverstringServer identifier (UUID or short ID)
scheduleintegerSchedule ID

Example Request

curl -X POST "https://your-panel.com/api/client/servers/d3aac109/schedules/2/execute" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json"

Success Response (204)

Returns empty response body with status code 204.

Error Responses

Schedule Already Running (409)

{
"errors": [
{
"code": "ConflictingServerStateException",
"status": "409",
"detail": "This schedule is already running and cannot be executed again."
}
]
}

Schedule Inactive (400)

{
"errors": [
{
"code": "BadRequestHttpException",
"status": "400",
"detail": "Cannot execute an inactive schedule."
}
]
}

Schedule Tasks Management

List Schedule Tasks

GET /api/client/servers/{server}/schedules/{schedule}/tasks

Create Schedule Task

POST /api/client/servers/{server}/schedules/{schedule}/tasks

Request Body

FieldTypeRequiredDescription
actionstringYesTask action: command, power, backup
payloadstringYesAction payload (command text, power action, etc.)
time_offsetintegerYesDelay in seconds from previous task
continue_on_failurebooleanNoContinue if task fails (default: false)

Task Actions

ActionPayloadDescription
commandCommand stringExecute console command
powerstart, stop, restart, killPower management action
backupEmpty string or backup nameCreate server backup

Example Create Task

curl -X POST "https://your-panel.com/api/client/servers/d3aac109/schedules/12/tasks" \
-H "Authorization: Bearer ptlc_YOUR_API_KEY" \
-H "Accept: Application/vnd.pterodactyl.v1+json" \
-H "Content-Type: application/json" \
-d '{
"action": "backup",
"payload": "Scheduled backup",
"time_offset": 0,
"continue_on_failure": false
}'

Update Schedule Task

PATCH /api/client/servers/{server}/schedules/{schedule}/tasks/{task}

Delete Schedule Task

DELETE /api/client/servers/{server}/schedules/{schedule}/tasks/{task}


Common Schedule Patterns

Daily Server Restart

{
"name": "Daily Restart",
"minute": "0",
"hour": "4",
"day_of_month": "*",
"month": "*",
"day_of_week": "*",
"tasks": [
{
"action": "command",
"payload": "say Server restarting in 30 seconds!",
"time_offset": 0
},
{
"action": "power",
"payload": "restart",
"time_offset": 30
}
]
}

Weekly Backup with Cleanup

{
"name": "Weekly Maintenance",
"minute": "0",
"hour": "3",
"day_of_month": "*",
"month": "*",
"day_of_week": "0",
"tasks": [
{
"action": "command",
"payload": "save-all",
"time_offset": 0
},
{
"action": "backup",
"payload": "Weekly backup",
"time_offset": 10
},
{
"action": "command",
"payload": "say Weekly backup completed",
"time_offset": 300
}
]
}

Hourly Resource Check

{
"name": "Resource Monitor",
"minute": "0",
"hour": "*",
"day_of_month": "*",
"month": "*",
"day_of_week": "*",
"only_when_online": true,
"tasks": [
{
"action": "command",
"payload": "memory",
"time_offset": 0
},
{
"action": "command",
"payload": "tps",
"time_offset": 5
}
]
}

Schedule Best Practices

Timing Considerations

  • Avoid peak hours: Schedule intensive tasks during low usage periods
  • Stagger schedules: Don't run multiple heavy tasks simultaneously
  • Time zones: All times are in server timezone (usually UTC)
  • Buffer time: Add delays between tasks to prevent conflicts

Task Sequencing

  • Order matters: Tasks execute in sequence_id order
  • Use time_offset: Add delays between tasks for proper execution
  • Error handling: Use continue_on_failure appropriately
  • Test first: Execute schedules manually before enabling

Resource Management

  • Monitor performance: Watch server performance during scheduled tasks
  • Backup timing: Schedule backups when server load is low
  • Restart coordination: Notify users before automated restarts
  • Cleanup tasks: Regular cleanup of logs and temporary files

Security

  • Limit permissions: Only grant schedule permissions to trusted users
  • Validate commands: Ensure scheduled commands are safe
  • Monitor execution: Review schedule logs regularly
  • Disable unused: Deactivate schedules that are no longer needed

Schedule Limits and Quotas

Default Limits

ResourceDefault LimitDescription
Schedules per server10-50Varies by hosting plan
Tasks per schedule20Maximum tasks in one schedule
Execution timeout900 secondsMaximum task execution time
Concurrent schedules3Maximum simultaneous executions

Performance Considerations

  • Heavy operations: Backups and restarts consume significant resources
  • Command execution: Long-running commands may timeout
  • Schedule overlap: Prevent schedules from overlapping execution
  • Resource monitoring: Monitor CPU and memory during scheduled tasks

Common Error Codes

StatusCodeDescription
400TooManySchedulesExceptionSchedule limit reached
400BadRequestHttpExceptionInvalid schedule configuration
401InvalidCredentialsExceptionInvalid API key
403InsufficientPermissionsExceptionMissing required permissions
404NotFoundHttpExceptionSchedule not found
409ConflictingServerStateExceptionSchedule already running
422ValidationExceptionInvalid request data

Required Permissions

Schedule operations require specific permissions:

PermissionDescription
schedule.readView schedules and tasks
schedule.createCreate new schedules
schedule.updateModify existing schedules
schedule.deleteDelete schedules
schedule.executeManually trigger schedules

Monitoring Schedule Execution

Execution Tracking

Monitor schedule execution through:

  • last_run_at: Last successful execution time
  • next_run_at: Next scheduled execution time
  • is_processing: Current execution status
  • Task logs: Individual task execution results

Troubleshooting

Common schedule issues:

  • Cron expression errors: Validate cron syntax
  • Permission issues: Ensure proper API permissions
  • Resource conflicts: Check for overlapping schedules
  • Server state: Verify server is in correct state for tasks

Source References

Controller: ScheduleController
Task Controller: ScheduleTaskController
Routes: api-client.php - Schedule endpoints
Schedule Model: Schedule.php
Task Model: Task.php
Schedule Service: ScheduleCreationService

Next Steps