Create a schedule
Creates a new scheduled task that will automatically run the agent based on the specified schedule.
Schedule Types:
- CRON (3): Use cronExpression to define a recurring schedule
- RunOnce (1): Requires startTime (must be at least 1 minute in the future) - runs once at the specified date/time
- RunEvery (2): Uses runEveryCount and runEveryPeriod (0=minutes, 1=hours, 2=days, 3=weeks, 4=months). Optional startTime for first run (must be in the future if provided).
StartTime Validation:
- For RunOnce: Required. Must be at least 1 minute in the future (UTC).
- For RunEvery: Optional. If provided, must be in the future (UTC). Determines when the first run occurs.
- For CRON: Not used. Schedule is determined by cronExpression.
CRON Schedule Example:
{
"name": "Daily Morning Run",
"scheduleType": 3,
"cronExpression": "0 9 * * 1,4",
"timezone": "America/New_York",
"isEnabled": true
}
Run Once Example:
{
"name": "One-time Run",
"scheduleType": 1,
"startTime": "2026-01-20T14:30:00Z",
"timezone": "America/New_York",
"isEnabled": true
}
Run Every Example (every 30 minutes):
{
"name": "Frequent Check",
"scheduleType": 2,
"runEveryCount": 30,
"runEveryPeriod": 0,
"startTime": "2026-01-17T10:00:00Z",
"timezone": "America/Denver",
"isEnabled": true
}
Encrypted input parameters
Prefix a parameter name with ? to have its value encrypted at rest and hidden in
the Run log — for example "?apiKey" instead of "apiKey". The name you send decides
this. Sending a name without the ? prefix stores and logs the value in clear text,
even when the Agent defines that parameter as encrypted. Omitting a parameter
entirely leaves the Agent’s own definition in effect, encryption included.
If you send both "name" and "?name", the ?-prefixed entry is used and the plain
one is discarded. The request still succeeds.
A Schedule stores its input parameters, so a clear-text value is also returned in
clear text by GET /api/v1/agent/{agentId}/schedules to any caller with an API key
and read access to the Agent’s Space. Send ?name for anything sensitive.
Call GET /api/v1/agent/{agentId}/input-parameters to see which parameters an Agent
defines as encrypted.
curl --request POST \
--url https://api.example.com/api/v1/agent/{agentId}/schedules \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"cronExpression": "<string>",
"localSchedule": "<string>",
"timezone": "<string>",
"startTime": "2026-01-20T14:30:00Z",
"inputParameters": "<string>",
"isEnabled": true,
"runEveryCount": 123,
"runEveryPeriod": 123,
"parallelism": 123,
"parallelMaxConcurrency": 123,
"proxyPoolId": 123,
"serverGroupId": 123,
"isExclusive": true,
"isWaitOnFailure": true
}
'import requests
url = "https://api.example.com/api/v1/agent/{agentId}/schedules"
payload = {
"name": "<string>",
"cronExpression": "<string>",
"localSchedule": "<string>",
"timezone": "<string>",
"startTime": "2026-01-20T14:30:00Z",
"inputParameters": "<string>",
"isEnabled": True,
"runEveryCount": 123,
"runEveryPeriod": 123,
"parallelism": 123,
"parallelMaxConcurrency": 123,
"proxyPoolId": 123,
"serverGroupId": 123,
"isExclusive": True,
"isWaitOnFailure": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
cronExpression: '<string>',
localSchedule: '<string>',
timezone: '<string>',
startTime: '2026-01-20T14:30:00Z',
inputParameters: '<string>',
isEnabled: true,
runEveryCount: 123,
runEveryPeriod: 123,
parallelism: 123,
parallelMaxConcurrency: 123,
proxyPoolId: 123,
serverGroupId: 123,
isExclusive: true,
isWaitOnFailure: true
})
};
fetch('https://api.example.com/api/v1/agent/{agentId}/schedules', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/agent/{agentId}/schedules",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'cronExpression' => '<string>',
'localSchedule' => '<string>',
'timezone' => '<string>',
'startTime' => '2026-01-20T14:30:00Z',
'inputParameters' => '<string>',
'isEnabled' => true,
'runEveryCount' => 123,
'runEveryPeriod' => 123,
'parallelism' => 123,
'parallelMaxConcurrency' => 123,
'proxyPoolId' => 123,
'serverGroupId' => 123,
'isExclusive' => true,
'isWaitOnFailure' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/agent/{agentId}/schedules"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"cronExpression\": \"<string>\",\n \"localSchedule\": \"<string>\",\n \"timezone\": \"<string>\",\n \"startTime\": \"2026-01-20T14:30:00Z\",\n \"inputParameters\": \"<string>\",\n \"isEnabled\": true,\n \"runEveryCount\": 123,\n \"runEveryPeriod\": 123,\n \"parallelism\": 123,\n \"parallelMaxConcurrency\": 123,\n \"proxyPoolId\": 123,\n \"serverGroupId\": 123,\n \"isExclusive\": true,\n \"isWaitOnFailure\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/agent/{agentId}/schedules")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"cronExpression\": \"<string>\",\n \"localSchedule\": \"<string>\",\n \"timezone\": \"<string>\",\n \"startTime\": \"2026-01-20T14:30:00Z\",\n \"inputParameters\": \"<string>\",\n \"isEnabled\": true,\n \"runEveryCount\": 123,\n \"runEveryPeriod\": 123,\n \"parallelism\": 123,\n \"parallelMaxConcurrency\": 123,\n \"proxyPoolId\": 123,\n \"serverGroupId\": 123,\n \"isExclusive\": true,\n \"isWaitOnFailure\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/agent/{agentId}/schedules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"cronExpression\": \"<string>\",\n \"localSchedule\": \"<string>\",\n \"timezone\": \"<string>\",\n \"startTime\": \"2026-01-20T14:30:00Z\",\n \"inputParameters\": \"<string>\",\n \"isEnabled\": true,\n \"runEveryCount\": 123,\n \"runEveryPeriod\": 123,\n \"parallelism\": 123,\n \"parallelMaxConcurrency\": 123,\n \"proxyPoolId\": 123,\n \"serverGroupId\": 123,\n \"isExclusive\": true,\n \"isWaitOnFailure\": true\n}"
response = http.request(request)
puts response.read_body{
"id": 123,
"configId": 123,
"name": "<string>",
"schedule": "<string>",
"localSchedule": "<string>",
"timezone": "<string>",
"nextRunTime": "2023-11-07T05:31:56Z",
"startTime": "2023-11-07T05:31:56Z",
"scheduleType": 0,
"isEnabled": true,
"runEveryCount": 123,
"runEveryPeriod": 123,
"inputParameters": "<string>",
"parallelism": 123,
"parallelMaxConcurrency": 123,
"parallelExport": "Combined",
"proxyPoolId": 123,
"serverGroupId": 123,
"logLevel": "Fatal",
"logMode": "Text",
"isExclusive": true,
"isWaitOnFailure": true,
"created": "2023-11-07T05:31:56Z",
"updated": "2023-11-07T05:31:56Z"
}{
"statusCode": 123,
"statusDescription": "<string>",
"message": "<string>",
"severity": 0,
"errorCode": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}Authorizations
API Key authorization header. Example: "Authorization: ApiKey {your-api-key}"
OAuth 2.0 Bearer token. Example: "Authorization: Bearer {access-token}"
Path Parameters
The ID of the agent
Body
The schedule configuration
Request model for creating a new schedule
Name of the schedule (required)
Cron expression for the schedule (e.g., "0 9 * * 1,4" for Mon/Thu at 9am)
Local schedule expression (human readable)
Timezone for the schedule (e.g., "America/New_York")
Start date/time for the schedule in UTC.
- Required for RunOnce schedules (must be at least 1 minute in the future).
- Optional for RunEvery schedules (if provided, must be in the future; determines when the first run occurs).
- Not used for CRON schedules.
"2026-01-20T14:30:00Z"
JSON string of input parameters for scheduled runs
0 = None; 1 = RunOnce; 2 = RunEvery; 3 = CRON
0, 1, 2, 3 Whether the schedule is enabled
Run every N periods (used with RunEveryPeriod)
Period unit for RunEveryCount (1=minutes, 2=hours, 3=days, 4=weeks, 5=months)
Parallelism level for the scheduled run
Max concurrency for parallel runs
0 = Combined; 1 = Separated
Combined, Separated Proxy pool ID to use for scheduled runs
Server group ID for scheduled runs (optional). When specified, the schedule will run on servers in this group.
0 = Fatal; 1 = Error; 2 = Warning; 3 = Info
Fatal, Error, Warning, Info 0 = Text; 1 = TextAndHtml
Text, TextAndHtml Whether to run exclusively (no concurrent runs)
Whether to wait on failure before retrying
Response
Returns the created schedule
Represents a scheduled task for an agent in the External API
0 = None; 1 = RunOnce; 2 = RunEvery; 3 = CRON
0, 1, 2, 3 0 = Combined; 1 = Separated
Combined, Separated 0 = Fatal; 1 = Error; 2 = Warning; 3 = Info
Fatal, Error, Warning, Info 0 = Text; 1 = TextAndHtml
Text, TextAndHtml