Schedules
Run an agent, group, or pipeline on a recurring or one-time schedule.
A schedule starts an agent, a group, or a pipeline automatically. Runs started by a schedule report triggerSource: "Schedule" in run history.
Most teams manage schedules in the dashboard. The API is there for when you want to create them from your own systems.
Schedule types
scheduleType | Runs | Uses |
|---|---|---|
Basic | Every N units from a start time | intervalValue + intervalUnit (Minutes, Hours, Days, Weeks) |
Cron | On a cron expression | cronExpression — six fields, starting with seconds |
Once | Exactly once | startTime |
Every schedule has a timeZoneId (IANA, e.g. America/Chicago; defaults to UTC), so "02:00 daily" means 02:00 in that zone.
Cron has six fields
NexqData cron expressions include seconds: 0 0 2 * * * is 02:00:00 every day. A five-field expression won't parse the way you expect.
Create a schedule
/{
"targetType": "Agent",
"targetId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"scheduleType": "Cron",
"cronExpression": "0 0 2 * * *",
"startTime": "2026-09-24T00:00:00",
"timeZoneId": "America/Chicago",
"inputParameters": "{\"LastName\":\"Doe\"}"
}| Field | Required | Description |
|---|---|---|
targetType | — | Agent (default), Group, or Pipeline. |
targetId | Yes | The target's id (GUID). |
scheduleType | Yes | Basic, Cron, or Once. |
intervalValue, intervalUnit | Basic | Every how many of which unit. |
cronExpression | Cron | Six fields, starting with seconds. |
startTime | Yes | Wall-clock time in timeZoneId, with no offset. |
timeZoneId | Yes | IANA time zone. Defaults to UTC. |
inputParameters | — | Inputs for each run, as a JSON-encoded string — the same format as starting a run. |
isEnabled | — | Defaults to true. Send false to create it paused. |
The response's data is the saved schedule, including nextRunTime.
Check an expression before you save it:
/Takes the same body and returns the upcoming run times (UTC), or 400 with the reason it's invalid.
List schedules
/All your schedules. Pass one of agentId, groupId, or pipelineId to get just that target's schedules.
For a large list, use the page-numbered version:
/| Query parameter | Default | Description |
|---|---|---|
q | — | Matches the target's name. |
status | all | Waiting, Running, or Disabled — comma-separate to combine. |
page, pageSize | 1, 25 | pageSize up to 100. |
Besides items and total, the page reports totalSchedules, enabledCount, waitingCount, runningCount, and the nextRunTime across all your schedules.
| Field | Meaning |
|---|---|
status | The schedule's own state: Waiting for its next run, Running while it starts one, or Disabled. |
description | A readable summary, e.g. "Runs every 2 days". |
nextRunTime, lastRunTime | When it runs next, and last ran (UTC). |
lastJobStatusName, lastJobId | How the job it last started went, and which job that was. |
errorMessage | Why the last attempt to start failed, if it did. |
Upcoming runs
/Every scheduled run between from and to (default: now to 42 days ahead; at most 120 days), across your schedules. Pass agentId for one agent's.
Change a schedule
| Endpoint | Does |
|---|---|
PUT /api/schedules/{id} | Replace the schedule. Takes the same body as create. |
POST /api/schedules/{id}/enabled | Enable or pause it with { "isEnabled": false }. |
DELETE /api/schedules/{id} | Delete it. |
POST /api/schedules/bulk/enabled | Enable or pause several: { "ids": [...], "isEnabled": false }. |
POST /api/schedules/bulk/delete | Delete several: { "ids": [...] }. |
Bulk calls return affected and skipped counts. Ids you can't access, or that don't exist, are skipped rather than failing the call.
Run a schedule now
/Starts the schedule's target immediately, without changing its timetable. The body is optional; send { "inputParameters": "..." } to override the inputs for this one run.
The response says what started, by target: agentJobId for an agent, groupRunId for a group, or pipelineRunId for a pipeline. Follow it as you would a job, group run, or pipeline run.