Manage cron jobs
List, add, change, disable and delete the scheduled commands (cron jobs) of a hosting account through the API, and follow their last run.
This guide shows how to manage the cron jobs of a hosting account with the API. A cron job runs a command on a schedule inside one site’s web container, as the site user.
What you need
Section titled “What you need”- An API key with the scope
crons:readto list cron jobs andcrons:writeto add, change or delete them (scopes). - The account id and the site id of the site that runs the command. List them with
GET /api/v1/accountsandGET /api/v1/accounts/{account_id}/sites. - A plan that allows cron jobs. Without it, adding a job answers
403 plan_feature_disabled.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export ACCOUNT_ID="5a5a5a5a-1111-4222-8333-444455556666"
export SITE_ID="6b6b6b6b-1111-4222-8333-444455556666"
1. List the cron jobs
Section titled “1. List the cron jobs”GET /api/v1/accounts/{id}/crons returns every cron job of the account, with the result of its last run.
curl -fsS "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY"
{
"items": [
{
"id": "8d8d8d8d-1111-4222-8333-444455556666",
"account_id": "5a5a5a5a-1111-4222-8333-444455556666",
"site_id": "6b6b6b6b-1111-4222-8333-444455556666",
"schedule": "*/15 * * * *",
"command": "echo hello from cron",
"enabled": true,
"source": "user",
"last_run_at": "2026-11-14T09:45:00Z",
"last_exit": 0
}
],
"sync": { "state": "applied" }
}
last_run_atandlast_exitare empty (null) until the job has run once. An exit code other than0means the command failed; its output is in the site’scron.log.sourceisuserfor jobs you added andmigrationfor jobs that a cPanel migration carried over.sync.statesays whether the server has applied the list:applied,pendingorfailed.
2. Add a cron job
Section titled “2. Add a cron job”POST /api/v1/accounts/{id}/crons adds a job. site_id, schedule and command are required; enabled
defaults to true.
curl -fsS -X POST "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"site_id": "'"$SITE_ID"'", "schedule": "*/15 * * * *", "command": "echo hello from cron"}'
The answer is 201 with the new job in cron and a job_id: the server applies the change as a
job, so the cron job is on the server a moment later. Keep the id of the new job as CRON_ID for the next steps.
scheduleis five fields (minute, hour, day of month, month, day of week) or one of@hourly,@daily,@weekly,@monthly,@yearly.@rebootis not supported. Times are UTC.commandis printable text, at most 1024 bytes. A command runs for at most one hour.- An account has at most 100 cron jobs.
3. Change or disable a cron job
Section titled “3. Change or disable a cron job”PATCH /api/v1/crons/{id} changes any of schedule, command, site_id and enabled; members you leave out
stay as they are. Disabling keeps the job in the list.
curl -fsS -X PATCH "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
-d '{"enabled": false}'
The answer has the same shape as for a new job: cron and job_id. To send the change only if nobody
else changed the job meanwhile, use an If-Match header.
4. Delete a cron job
Section titled “4. Delete a cron job”curl -fsS -X DELETE "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
-H "Authorization: Bearer $PLUSPANEL_API_KEY"
The answer is 204 with no body.
Follow the change on the server
Section titled “Follow the change on the server”A change returns before the server has applied it. To wait for it, read the job_id with
GET /api/v1/jobs/{id} (scope jobs:read) until its status is final, or watch
GET .../crons until sync.state is applied. A failed apply shows as
sync.state: "failed".
Errors
Section titled “Errors”| Status | Code | Meaning |
|---|---|---|
401 |
invalid_api_key |
The key is missing, expired or revoked. |
403 |
plan_feature_disabled |
The account’s plan does not allow cron jobs. |
403 |
The key has no crons scope, or the user may not manage this account. |
|
404 |
The account or cron job does not exist or is not visible to you. | |
409 |
crons_unsupported_agent |
The server’s agent does not run cron jobs. |
409 |
conflict |
The account already has 100 cron jobs. |
422 |
validation_failed |
The schedule or command is invalid, or the site is not a site of the account. |
Errors are problem details: branch on code.
Events
Section titled “Events”When the server has applied a change, the job finishes and a job.succeeded event is sent (job.failed if it
failed); data.object_id is the job_id of the answer. Subscribe to them as described in
webhooks.
Related
Section titled “Related”- Sites: cron jobs in the panel.
- API reference: every
cronsoperation, with its fields. - API conventions: errors, idempotency and ETags.
- Authentication & API keys: scopes and key handling.