Skip to main content
POST
Create a scheduled task
Saves a prompt for the agent to run on cronExpression in timezone, or only on demand without a cron. Runs act as the caller. A cron fires at most hourly (400 otherwise), and a user can have 20 active tasks (409 past that).

Authorizations

Authorization
string
header
required

Token authentication. Send Authorization: Bearer <YOUR_TOKEN>.

Path Parameters

deploymentId
integer
required

Body

application/json

CreateScheduledTaskInput

name
string
required
Required string length: 1 - 255
prompt
string
required

What the agent is asked on every run, shown as the task's Instructions in Cube. Each run starts a new chat thread with no memory of earlier ones, so write the whole request.

Minimum string length: 1
agentId
integer | null

The agent that runs the task. Omit for the deployment default.

cronExpression
string | null

Standard 5-field cron (minute hour day-of-month month day-of-week), e.g. 0 9 * * 1-5 for 9:00 on weekdays. A task runs at most once an hour, so the minute field is a single number. Null or omitted makes the task Manual: it runs only when started with POST /scheduled-tasks/{taskId}/run.

Maximum string length: 100
description
string | null
isEnabled
boolean | null

Create the schedule paused with false. Defaults to true.

timezone
string | null

IANA time zone the cron is read in, e.g. America/New_York. Defaults to UTC.

Maximum string length: 100

Response

200 - application/json
deploymentId
integer
required
id
integer
required
isEnabled
boolean
required

False while the schedule is paused.

name
string
required
prompt
string
required

What the agent is asked on every run, shown as the task's Instructions in Cube. Each run starts a new chat thread, so the prompt has to stand on its own.

timezone
string
required

IANA time zone the cron is read in, e.g. America/New_York. Defaults to UTC.

userId
integer
required

The creator. Every run executes as this user, and only they or an admin may change, delete or run the task.

agentId
integer | null

The agent that runs the task; null runs the deployment default.

cronExpression
string | null

Standard 5-field cron (minute hour day-of-month month day-of-week), e.g. 0 9 * * 1-5 for 9:00 on weekdays. Null when the task is Manual: it runs only when started with POST /scheduled-tasks/{taskId}/run.

description
string | null
nextRunAt
string | null

When the schedule next fires (ISO 8601, UTC); null for a Manual or paused task.