Reference

Schedule Endpoints


Manage cron-based recurring workflow executions. Schedules store a cron expression and a workflow configuration (task_template); when a schedule fires, the platform starts a new workflow execution automatically.

Create Schedule

1
POST /api/v1/schedules
2
Content-Type: application/json
3
4
{
5
"name": "nightly-report",
6
"description": "Generate daily analytics report at 2 AM UTC",
7
"cronExpression": "0 0 2 * * *",
8
"timezone": "UTC",
9
"taskTemplate": {
10
"workflowType": "daily_report",
11
"taskQueue": "reports",
12
"namespace": "production",
13
"input": {
14
"recipients": ["team@example.com"]
15
}
16
},
17
"maxInstances": 1,
18
"overlapPolicy": "skip",
19
"maxRuns": 365,
20
"tags": ["analytics", "daily"]
21
}

Response (201 Created):

1
{
2
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3
"name": "nightly-report",
4
"description": "Generate daily analytics report at 2 AM UTC",
5
"cronExpression": "0 0 2 * * *",
6
"timezone": "UTC",
7
"enabled": true,
8
"taskTemplate": {
9
"workflow_type": "daily_report",
10
"task_queue": "reports",
11
"namespace": "production",
12
"input": { "recipients": ["team@example.com"] }
13
},
14
"maxInstances": 1,
15
"overlapPolicy": "skip",
16
"maxRuns": 365,
17
"status": "active",
18
"nextRunAt": "2024-01-08T02:00:00Z",
19
"runCount": 0,
20
"successCount": 0,
21
"failureCount": 0,
22
"tags": ["analytics", "daily"],
23
"metadata": {},
24
"createdAt": "2024-01-07T15:30:00Z",
25
"updatedAt": "2024-01-07T15:30:00Z"
26
}

Task Template

The taskTemplate object configures which workflow to start on each trigger:

FieldTypeDefaultDescription
workflowTypestringrequiredWorkflow name registered by workers
taskQueuestring"default"Task queue for the workflow
namespacestring"default"Namespace for the execution
inputobjectnullInput payload passed to the workflow

Overlap Policy

Controls behavior when the previous execution is still running when a new trigger fires:

ValueDescription
skipSkip the new run (default)
queueQueue the new run to start after the current one completes
replaceCancel the running execution and start a new one
parallelRun concurrently (up to maxInstances)

Cron Expression Format

Uses 6-field cron expressions (seconds included):

FieldValues
Second0-59
Minute0-59
Hour0-23
Day of Month1-31
Month1-12 or JAN-DEC
Day of Week0-6 or SUN-SAT

Examples:

ExpressionDescription
0 0 2 * * *Every day at 2:00 AM
0 */15 * * * *Every 15 minutes
0 0 9 * * MON-FRIWeekdays at 9:00 AM

Get Schedule

1
GET /api/v1/schedules/:id

Response:

1
{
2
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3
"name": "nightly-report",
4
"cronExpression": "0 0 2 * * *",
5
"timezone": "UTC",
6
"enabled": true,
7
"status": "active",
8
"nextRunAt": "2024-01-08T02:00:00Z",
9
"lastRunAt": "2024-01-07T02:00:00Z",
10
"runCount": 30,
11
"successCount": 29,
12
"failureCount": 1,
13
"...": "..."
14
}

Update Schedule

Partial update — only provided fields are changed.

1
PUT /api/v1/schedules/:id
2
Content-Type: application/json
3
4
{
5
"cronExpression": "0 0 3 * * *",
6
"description": "Moved to 3 AM UTC"
7
}

Response: Updated schedule object (same shape as create response).


Delete Schedule

1
DELETE /api/v1/schedules/:id

Response:

1
{
2
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3
"status": "deleted",
4
"message": "Schedule deleted successfully"
5
}

List Schedules

1
GET /api/v1/schedules?status=active&name=report&limit=50&offset=0

Query Parameters:

ParameterTypeDefaultDescription
statusstring—Filter by status (active, paused, completed, failed)
namestring—Filter by name (case-insensitive substring match)
limitinteger50Results per page
offsetinteger0Pagination offset

Response:

1
{
2
"schedules": [
3
{
4
"id": "a1b2c3d4-...",
5
"name": "nightly-report",
6
"cronExpression": "0 0 2 * * *",
7
"status": "active",
8
"nextRunAt": "2024-01-08T02:00:00Z",
9
"runCount": 30,
10
"..."
11
}
12
],
13
"total": 12,
14
"count": 12,
15
"offset": 0
16
}

Pause Schedule

Temporarily stop a schedule from firing without deleting it. The schedule retains its configuration and run history.

1
POST /api/v1/schedules/:id/pause

Response:

1
{
2
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3
"status": "paused",
4
"message": "Schedule paused successfully"
5
}

Resume Schedule

Resume a paused schedule. The next fire time is recalculated from the current time.

1
POST /api/v1/schedules/:id/resume

Response:

1
{
2
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3
"status": "active",
4
"message": "Schedule resumed successfully"
5
}

Schedule vs. Durable Timer Loop

Orcher supports two patterns for recurring work:

Cron Schedule (this API)Durable Timer Loop
HowServer-side cron triggerctx.sleep() in workflow code
LifecycleIndependent of workerTied to a long-running workflow execution
ManagementCRUD via REST APIManaged through workflow execution
Use whenStandard cron jobs, ops-managed schedulesComplex recurring logic with state between iterations

See Scheduled Jobs for the durable timer loop pattern.


Next Steps