Cron jobs
API reference for cron jobs that run as a website's or app's own Linux user - creating, changing, running now and reading their run history.
A cron job runs one or more commands on a schedule as the Linux user of a website or app. It is installed on the server by a job, then run by the server's own cron daemon, so it keeps running while the panel is down; the agent reports each run with its next request. Commands run in order, without a shell. The last 50 runs of each job are kept, with up to 16 KB of output each.
Hosting customers reach the cron jobs of their own websites and apps, and creating one counts against their plan. For the workflow, see Cron jobs.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/cron-jobs | List cron jobs |
| POST | /api/v1/cron-jobs | Create a cron job |
| GET | /api/v1/cron-jobs/:id | Get a cron job |
| PATCH | /api/v1/cron-jobs/:id | Update a cron job |
| DELETE | /api/v1/cron-jobs/:id | Delete a cron job |
| POST | /api/v1/cron-jobs/:id/run | Run a cron job now |
| GET | /api/v1/cron-jobs/:id/runs | List runs |
The cron job object
| Field | Type | Description |
|---|---|---|
id, serverId, serverName | string | The cron job and its server. |
serverTimezone | string or null | The server's time zone: schedules run in it. |
owner | object | { type, id, name }: the website or app, and the Linux user it runs as. |
name | string | Up to 100 characters. |
schedule, description | string | The cron expression, and in words (Every day at 03:00). |
commands | string | One command per line. |
workingDir | string | The folder inside the site or app it starts in; empty for its home folder. |
timeoutSeconds | integer | A run is stopped after this long. |
enabled | boolean | Paused when false. |
appEnv | boolean | Apps only: load the app's environment variables. |
status | string | creating, active, updating, deleting or failed. |
pending | object or null | Settings being sent to the server. |
lastJobId, lastError | The last job, and { code, message } of its failure. | |
lastRun | object or null | { at, status, exitCode, durationMs }. |
List cron jobs
/api/v1/cron-jobsReturns cron jobs a page at a time.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
serverId | string (UUID) | No | Only cron jobs on this server. |
ownerType, ownerId | string | No | Only cron jobs of this website or application. |
search | string | No | Part of the name or of the Linux user's name. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
sort, order | string | No | name (default), createdAt or lastRunAt; asc (default) or desc. |
Example request
curl "https://panel.example.com/api/v1/cron-jobs?ownerType=application&ownerId=3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.cronJobs.list({ ownerType: 'application', ownerId: appId });Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "8f9a0b1c-…",
"serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"serverName": "web-1",
"serverTimezone": "UTC",
"owner": { "type": "application", "id": "3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7", "name": "shop-api" },
"name": "Nightly cleanup",
"schedule": "0 3 * * *",
"description": "Every day at 03:00",
"commands": "node scripts/cleanup.js",
"workingDir": "current",
"timeoutSeconds": 3600,
"enabled": true,
"appEnv": true,
"status": "active",
"pending": null,
"lastJobId": "…",
"lastError": null,
"lastRun": { "at": "2026-11-10T03:00:00.000Z", "status": "succeeded", "exitCode": 0, "durationMs": 1840 },
"createdAt": "2026-10-12T09:00:00.000Z",
"updatedAt": "2026-10-12T09:00:05.000Z"
}
],
"pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
},
"message": "OK",
"requestId": "…"
}Create a cron job
/api/v1/cron-jobsCreates a cron job and installs it on the website's or app's server (CREATE_CRON).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
ownerType | string | Yes | website or application. |
ownerId | string (UUID) | Yes | The website or app it runs as. |
name | string | Yes | Up to 100 characters. |
schedule | string | Yes | A five-field cron expression, such as */15 * * * *. |
commands | string | Yes | Up to 10 lines of up to 500 characters, one command per line, run in order without a shell. |
workingDir | string | No | A folder inside the site or app, such as current or public. Default: its home folder. |
timeoutSeconds | integer | No | 10 to 86400. Default 3600. |
enabled | boolean | No | Default true. |
appEnv | boolean | No | Apps only: load the app's environment variables. Default false. |
Example request
curl https://panel.example.com/api/v1/cron-jobs \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ownerType": "website",
"ownerId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "WordPress cron",
"schedule": "*/15 * * * *",
"commands": "php wp-cron.php",
"workingDir": "public"
}'const { cronJob, job } = await panel.cronJobs.create({
ownerType: 'website',
ownerId: '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
name: 'WordPress cron',
schedule: '*/15 * * * *',
commands: 'php wp-cron.php',
workingDir: 'public',
});Response 202 Accepted: { cronJob, job } with the cron job in status creating, message Saving the cron job on the server.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such website or app, or not yours. |
| 409 | RESOURCE_NOT_READY | The website or app is not ready. |
| 409 | QUOTA_REACHED | A hosting customer's plan allows no more cron jobs (details: { kind, limit, used }). |
| 422 | VALIDATION_ERROR | An invalid schedule or command, appEnv on a website, or another invalid field. |
Get a cron job
/api/v1/cron-jobs/:idReturns one cron job object.
Example request
curl https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const cronJob = await panel.cronJobs.get(cronJobId);Response 200 OK: the cron job.
Update a cron job
/api/v1/cron-jobs/:idChanges any of name, schedule, commands, workingDir, timeoutSeconds, enabled and appEnv (send at least one). A change to the name alone, or no change at all, answers 200 OK with job: null; anything else sends the cron job to the server again and answers 202 Accepted with the job. A cron job whose creation failed is created again with the new settings. Set enabled to false to pause it.
Example request
curl https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c \
-X PATCH \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'const { cronJob, job } = await panel.cronJobs.update(cronJobId, { enabled: false });Response 202 Accepted with { cronJob, job } (message Saving the cron job on the server), or 200 OK with job: null (message Saved).
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No cron job with this id. |
| 409 | CRON_JOB_BUSY | A change to it is still running (details.jobId). |
| 409 | RESOURCE_NOT_READY | Its website or app is not ready. |
| 422 | VALIDATION_ERROR | No field given, or the result is invalid. |
Delete a cron job
/api/v1/cron-jobs/:idRemoves the cron job from its server (DELETE_CRON) and from the panel. A cron job whose creation failed is removed from the panel at once.
Example request
curl https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { job } = await panel.cronJobs.remove(cronJobId);Response 202 Accepted: { job }, message Deleting the cron job.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No cron job with this id. |
| 409 | CRON_JOB_BUSY | A change to it is still running. |
Run a cron job now
/api/v1/cron-jobs/:id/runRuns the cron job once now (RUN_CRON), as its own user. The run is recorded in its history with the trigger manual.
Example request
curl https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c/run \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { job } = await panel.cronJobs.run(cronJobId);
await panel.jobs.wait(job.id);Response 202 Accepted: { job }, message Running.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No cron job with this id. |
| 409 | CRON_JOB_NOT_READY | It is not set up on its server (save it again), or a change to it is still running. |
| 409 | DUPLICATE_OPERATION | A run started from the panel is already queued or running. |
List runs
/api/v1/cron-jobs/:id/runsReturns the cron job's runs, newest first, with their output.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | succeeded, failed, timed_out or skipped (the previous run was still going). |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
order | string | No | desc (default) or asc by start time. |
Example request
curl "https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c/runs?status=failed" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.cronJobs.runs(cronJobId, { status: 'failed' });Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": 1042,
"cronJobId": "8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c",
"trigger": "schedule",
"status": "failed",
"exitCode": 1,
"startedAt": "2026-11-10T03:00:00.000Z",
"finishedAt": "2026-11-10T03:00:02.000Z",
"durationMs": 1950,
"output": "Error: connect ECONNREFUSED 127.0.0.1:3306\n",
"outputTruncated": false,
"jobId": null
}
],
"pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
},
"message": "OK",
"requestId": "…"
}trigger is schedule (started by the server's cron daemon) or manual (started from the panel).
Backups
API reference for backing up websites, apps and databases, restoring and downloading backups, backup schedules, and S3 or SFTP backup storage.
Webhooks
API reference for outgoing webhooks - creating JSON, Slack and Discord webhooks, rotating signing secrets, sending tests and reading or redelivering deliveries.