API Reference

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.

Last updated

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.

MethodPathDescription
GET/api/v1/cron-jobsList cron jobs
POST/api/v1/cron-jobsCreate a cron job
GET/api/v1/cron-jobs/:idGet a cron job
PATCH/api/v1/cron-jobs/:idUpdate a cron job
DELETE/api/v1/cron-jobs/:idDelete a cron job
POST/api/v1/cron-jobs/:id/runRun a cron job now
GET/api/v1/cron-jobs/:id/runsList runs

The cron job object

FieldTypeDescription
id, serverId, serverNamestringThe cron job and its server.
serverTimezonestring or nullThe server's time zone: schedules run in it.
ownerobject{ type, id, name }: the website or app, and the Linux user it runs as.
namestringUp to 100 characters.
schedule, descriptionstringThe cron expression, and in words (Every day at 03:00).
commandsstringOne command per line.
workingDirstringThe folder inside the site or app it starts in; empty for its home folder.
timeoutSecondsintegerA run is stopped after this long.
enabledbooleanPaused when false.
appEnvbooleanApps only: load the app's environment variables.
statusstringcreating, active, updating, deleting or failed.
pendingobject or nullSettings being sent to the server.
lastJobId, lastErrorThe last job, and { code, message } of its failure.
lastRunobject or null{ at, status, exitCode, durationMs }.

List cron jobs

GET/api/v1/cron-jobs
Auth
Session cookie (+ CSRF token) or API token
Permission
cron.read
Token scope
read

Returns cron jobs a page at a time.

Query parameters

NameTypeRequiredDescription
serverIdstring (UUID)NoOnly cron jobs on this server.
ownerType, ownerIdstringNoOnly cron jobs of this website or application.
searchstringNoPart of the name or of the Linux user's name.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNoname (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

POST/api/v1/cron-jobs
Auth
Session cookie (+ CSRF token) or API token
Permission
cron.manage
Token scope
manage

Creates a cron job and installs it on the website's or app's server (CREATE_CRON).

Request body

FieldTypeRequiredDescription
ownerTypestringYeswebsite or application.
ownerIdstring (UUID)YesThe website or app it runs as.
namestringYesUp to 100 characters.
schedulestringYesA five-field cron expression, such as */15 * * * *.
commandsstringYesUp to 10 lines of up to 500 characters, one command per line, run in order without a shell.
workingDirstringNoA folder inside the site or app, such as current or public. Default: its home folder.
timeoutSecondsintegerNo10 to 86400. Default 3600.
enabledbooleanNoDefault true.
appEnvbooleanNoApps 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

StatusCodeWhen
404NOT_FOUNDNo such website or app, or not yours.
409RESOURCE_NOT_READYThe website or app is not ready.
409QUOTA_REACHEDA hosting customer's plan allows no more cron jobs (details: { kind, limit, used }).
422VALIDATION_ERRORAn invalid schedule or command, appEnv on a website, or another invalid field.

Get a cron job

GET/api/v1/cron-jobs/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
cron.read
Token scope
read

Returns 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

PATCH/api/v1/cron-jobs/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
cron.manage
Token scope
manage

Changes 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

StatusCodeWhen
404NOT_FOUNDNo cron job with this id.
409CRON_JOB_BUSYA change to it is still running (details.jobId).
409RESOURCE_NOT_READYIts website or app is not ready.
422VALIDATION_ERRORNo field given, or the result is invalid.

Delete a cron job

DELETE/api/v1/cron-jobs/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
cron.manage
Token scope
manage

Removes 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

StatusCodeWhen
404NOT_FOUNDNo cron job with this id.
409CRON_JOB_BUSYA change to it is still running.

Run a cron job now

POST/api/v1/cron-jobs/:id/run
Auth
Session cookie (+ CSRF token) or API token
Permission
cron.run
Token scope
deploy

Runs 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

StatusCodeWhen
404NOT_FOUNDNo cron job with this id.
409CRON_JOB_NOT_READYIt is not set up on its server (save it again), or a change to it is still running.
409DUPLICATE_OPERATIONA run started from the panel is already queued or running.

List runs

GET/api/v1/cron-jobs/:id/runs
Auth
Session cookie (+ CSRF token) or API token
Permission
cron.read
Token scope
read

Returns the cron job's runs, newest first, with their output.

Query parameters

NameTypeRequiredDescription
statusstringNosucceeded, failed, timed_out or skipped (the previous run was still going).
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
orderstringNodesc (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).