Skip to content

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.

  • An API key with the scope crons:read to list cron jobs and crons:write to 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/accounts and GET /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"

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_at and last_exit are empty (null) until the job has run once. An exit code other than 0 means the command failed; its output is in the site’s cron.log.
  • source is user for jobs you added and migration for jobs that a cPanel migration carried over.
  • sync.state says whether the server has applied the list: applied, pending or failed.

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.

  • schedule is five fields (minute, hour, day of month, month, day of week) or one of @hourly, @daily, @weekly, @monthly, @yearly. @reboot is not supported. Times are UTC.
  • command is printable text, at most 1024 bytes. A command runs for at most one hour.
  • An account has at most 100 cron jobs.

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.

curl -fsS -X DELETE "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY"

The answer is 204 with no body.

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".

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.

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.