Cron API Documentation#

Base Path#

/crons

Endpoints#

Cron View Management#

Get View List#

GET /views

Get all cron task views.

Create View#

POST /views

Request Body

{
  name: string,           // View name
  sorts?: Array<any>,     // Sort rules
  filters?: Array<any>,   // Filter rules
  filterRelation?: string // Filter relationship
}

Update View#

PUT /views

Request Body

{
  id: number,            // View ID
  name: string,          // View name
  sorts?: Array<any>,    // Sort rules
  filters?: Array<any>,  // Filter rules
  filterRelation?: string // Filter relationship
}

Delete View#

DELETE /views

Request Body

number[]  // Array of view IDs

Move View Position#

PUT /views/move

Request Body

{
  fromIndex: number,  // Original position
  toIndex: number,    // Target position
  id: number         // View ID
}

Disable View#

PUT /views/disable

Request Body

number[]  // Array of view IDs

Enable View#

PUT /views/enable

Request Body

number[]  // Array of view IDs

Cron Task Management#

Get Cron Task List#

GET /

Get list of cron tasks.

Get Task Details#

GET /detail

Get detailed information of specified task.

Create Cron Task#

POST /

Request Body

{
  command: string,         // Command to execute
  schedule: string,        // Cron expression
  name?: string,          // Task name
  labels?: string[],      // Labels
  sub_id?: number,        // Sub-task ID
  extra_schedules?: any[], // Additional scheduling rules
  task_before?: string,   // Pre-task
  task_after?: string     // Post-task
}

Run Task#

PUT /run

Request Body

number[]  // Array of task IDs

Stop Task#

PUT /stop

Request Body

number[]  // Array of task IDs

Remove Labels#

DELETE /labels

Request Body

{
  ids: number[],    // Array of task IDs
  labels: string[]  // Array of labels
}

Add Labels#

POST /labels

Request Body

{
  ids: number[],    // Array of task IDs
  labels: string[]  // Array of labels
}

Disable Task#

PUT /disable

Request Body

number[]  // Array of task IDs

Enable Task#

PUT /enable

Request Body

number[]  // Array of task IDs

Get Task Log#

GET /:id/log

Get execution log of specified task.

Update Task#

PUT /

Request Body

{
  id: number,
  command: string,
  schedule: string,
  name?: string,
  labels?: string[],
  sub_id?: number,
  extra_schedules?: any[],
  task_before?: string,
  task_after?: string
}

Delete, pin and unpin tasks#

[12,13]

Import tasks#

GET /import imports tasks from crontab. This request changes panel state.

Get a single task#

GET /:id returns task details for the supplied ID.

Update task status#

PUT /status accepts:

{
  ids: number[],
  status: string,
  pid?: string,
  log_path?: string,
  last_running_time?: number,
  last_execution_time?: number
}

List task log files#

GET /:id/logs lists the task's log files. Use the log API to read or download a file.

Execution options and task instances#

Creation and updates also accept:

Both create and update require command and schedule. Five-field schedules and schedules with a seconds field are supported; see Schedules and time zones for syntax.

ql task instances 12 --json
ql task instance-stop 12 34 --json

Log chunks#

GET /open/crons/:id/log accepts offset (non-negative byte offset), limit (at most 1048576 bytes), and boolean tail. Responses include data, logStatus, offset, nextOffset, total and truncated. HTTP chunk sizes use bytes; the CLI's --tail option uses lines.

See the remote CLI guide for pagination and run responses. The HTTP run endpoint accepts an ID array. An accepted request does not mean script execution has completed.

Schedules and time zones#

A common cron schedule has five fields: minute, hour, day of month, month and day of week. An optional seconds field can be added at the beginning. Legacy shorthand remains compatible; use explicit five-field or six-field schedules for new rules.

Month and weekday names, valid steps such as */5 and 0/5, and compatible L and # rules are supported. ? is allowed only in the day-of-month and day-of-week fields. H, bare /N steps such as /5, and unlisted Quartz extensions are not supported.

Supported periodic aliases are @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly and @minutely. @annually equals @yearly, @midnight equals @daily, and @minutely runs at second 0 of each minute. Startup and one-time tasks use separate @boot and @once modes.

Rules restricting both day of month and day of week use the Node scheduler with OR semantics: either field can trigger execution, and a time matching both triggers only once. Regular tasks, additional scheduling rules, subscription cron plans and system Node cron jobs share normalization and scheduling rules. Interval schedules have separate configuration. Cron expressions are validated and normalized through cron-parser; Node scheduling uses node-cron.

Disabling, deleting or updating a task invalidates queued triggers from its previous rule that have not started. During schedule restoration, invalid persisted task or subscription rules are skipped and logged; their configuration is retained for correction.

Rules and aliases use the panel process's time zone. After changing the time zone, restart the relevant services through the settings procedure for it to take effect. In time zones with daylight saving time, nonexistent local times during the spring transition are skipped, and the repeated hour in autumn does not run a second time. Asia/Shanghai is unaffected by this difference. Delayed triggers within the running process can join the existing execution queue; there is no persistent catch-up guarantee while the panel is stopped, or guarantee of a single execution across multiple panels.