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
1POST /api/v1/schedules2Content-Type: application/json34{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:
| Field | Type | Default | Description |
|---|---|---|---|
workflowType | string | required | Workflow name registered by workers |
taskQueue | string | "default" | Task queue for the workflow |
namespace | string | "default" | Namespace for the execution |
input | object | null | Input payload passed to the workflow |
Overlap Policy
Controls behavior when the previous execution is still running when a new trigger fires:
| Value | Description |
|---|---|
skip | Skip the new run (default) |
queue | Queue the new run to start after the current one completes |
replace | Cancel the running execution and start a new one |
parallel | Run concurrently (up to maxInstances) |
Cron Expression Format
Uses 6-field cron expressions (seconds included):
| Field | Values |
|---|---|
| Second | 0-59 |
| Minute | 0-59 |
| Hour | 0-23 |
| Day of Month | 1-31 |
| Month | 1-12 or JAN-DEC |
| Day of Week | 0-6 or SUN-SAT |
Examples:
| Expression | Description |
|---|---|
0 0 2 * * * | Every day at 2:00 AM |
0 */15 * * * * | Every 15 minutes |
0 0 9 * * MON-FRI | Weekdays at 9:00 AM |
Get Schedule
1GET /api/v1/schedules/:idResponse:
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.
1PUT /api/v1/schedules/:id2Content-Type: application/json34{5 "cronExpression": "0 0 3 * * *",6 "description": "Moved to 3 AM UTC"7}Response: Updated schedule object (same shape as create response).
Delete Schedule
1DELETE /api/v1/schedules/:idResponse:
1{2 "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",3 "status": "deleted",4 "message": "Schedule deleted successfully"5}List Schedules
1GET /api/v1/schedules?status=active&name=report&limit=50&offset=0Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | — | Filter by status (active, paused, completed, failed) |
name | string | — | Filter by name (case-insensitive substring match) |
limit | integer | 50 | Results per page |
offset | integer | 0 | Pagination 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": 016}Pause Schedule
Temporarily stop a schedule from firing without deleting it. The schedule retains its configuration and run history.
1POST /api/v1/schedules/:id/pauseResponse:
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.
1POST /api/v1/schedules/:id/resumeResponse:
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 | |
|---|---|---|
| How | Server-side cron trigger | ctx.sleep() in workflow code |
| Lifecycle | Independent of worker | Tied to a long-running workflow execution |
| Management | CRUD via REST API | Managed through workflow execution |
| Use when | Standard cron jobs, ops-managed schedules | Complex recurring logic with state between iterations |
See Scheduled Jobs for the durable timer loop pattern.
Next Steps
- Workflow Endpoints — Execute and monitor workflows
- Errors & Limits — Error handling and rate limiting