# Cron jobs

URL: https://docs.vaultpanel.net/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.

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](https://docs.vaultpanel.net/guides/backups-and-automation/cron-jobs).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/cron-jobs` | [List cron jobs](https://docs.vaultpanel.net/api-reference/cron-jobs#list-cron-jobs) |
| POST | `/api/v1/cron-jobs` | [Create a cron job](https://docs.vaultpanel.net/api-reference/cron-jobs#create-a-cron-job) |
| GET | `/api/v1/cron-jobs/:id` | [Get a cron job](https://docs.vaultpanel.net/api-reference/cron-jobs#get-a-cron-job) |
| PATCH | `/api/v1/cron-jobs/:id` | [Update a cron job](https://docs.vaultpanel.net/api-reference/cron-jobs#update-a-cron-job) |
| DELETE | `/api/v1/cron-jobs/:id` | [Delete a cron job](https://docs.vaultpanel.net/api-reference/cron-jobs#delete-a-cron-job) |
| POST | `/api/v1/cron-jobs/:id/run` | [Run a cron job now](https://docs.vaultpanel.net/api-reference/cron-jobs#run-a-cron-job-now) |
| GET | `/api/v1/cron-jobs/:id/runs` | [List runs](https://docs.vaultpanel.net/api-reference/cron-jobs#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

`GET /api/v1/cron-jobs` — Permission: cron.read — Token scope: read

Returns 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**

```bash
curl "https://panel.example.com/api/v1/cron-jobs?ownerType=application&ownerId=3e4f5a6b-7c8d-4e9f-a0b1-c2d3e4f5a6b7" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.cronJobs.list({ ownerType: 'application', ownerId: appId });
```

**Response** `200 OK`

```json
{
  "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` — 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**

| 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**

```bash
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"
  }'
```

**JavaScript**

```js
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

`GET /api/v1/cron-jobs/:id` — Permission: cron.read — Token scope: read

Returns one [cron job object](https://docs.vaultpanel.net/api-reference/cron-jobs#the-cron-job-object).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const cronJob = await panel.cronJobs.get(cronJobId);
```

**Response** `200 OK`: the cron job.

## Update a cron job

`PATCH /api/v1/cron-jobs/:id` — 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**

```bash
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 }'
```

**JavaScript**

```js
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

`DELETE /api/v1/cron-jobs/:id` — 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**

```bash
curl https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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

`POST /api/v1/cron-jobs/:id/run` — 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**

```bash
curl https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c/run \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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

`GET /api/v1/cron-jobs/:id/runs` — Permission: cron.read — Token scope: read

Returns 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**

```bash
curl "https://panel.example.com/api/v1/cron-jobs/8f9a0b1c-2d3e-4f5a-8b6c-7d8e9f0a1b2c/runs?status=failed" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.cronJobs.runs(cronJobId, { status: 'failed' });
```

**Response** `200 OK`

```json
{
  "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).
