Job Schedules Reference

Job schedules are managed entirely through GraphQL mutations. There are no dedicated REST endpoints for schedule CRUD operations.

This page documents the GraphQL operations, cron format, and timezone handling for scheduled jobs.

---

GraphQL Operations

Queries

Query	Parameters	Return Type	Description
jobSchedules	projectId: String!	[JobSchedule]	List all schedules in a project
jobSchedule	id: Long!	JobSchedule	Get a specific schedule

Mutations

Mutation	Parameters	Return Type	Description
createJobSchedule	input: JobScheduleInput!, projectId: String!	JobSchedule	Create a new schedule
updateJobSchedule	id: Long!, input: JobScheduleInput!	JobSchedule	Update an existing schedule
deleteJobSchedule	id: Long!	Boolean	Delete a schedule
toggleJobSchedule	id: Long!, enabled: Boolean!	Boolean	Enable or disable a schedule
runJobScheduleNow	id: Long!	Job	Immediately trigger a scheduled job

---

Cron Format

Schedules use standard 5-field Unix cron format:

minute  hour  day-of-month  month  day-of-week

Field	Allowed Values	Special Characters
Minute	0-59	, - * /
Hour	0-23	, - * /
Day of month	1-31	, - * /
Month	1-12	, - * /
Day of week	0-6 (Sun=0)	, - * /

info

The platform internally converts 5-field cron to Quartz 6-field format (prepending 0 for seconds and handling the day-of-week / day-of-month mutual exclusion). You do not need to worry about Quartz-specific syntax.

Examples

Cron Expression	Schedule
0 9 * * *	Every day at 9:00 AM
*/15 * * * *	Every 15 minutes
0 0 1 * *	First day of every month at midnight
30 14 * * 1-5	Weekdays at 2:30 PM
0 8 * * 1	Every Monday at 8:00 AM

---

Timezone

Schedules require an IANA timezone string. The cron expression is evaluated in the specified timezone.

Common timezone values:

Timezone	UTC Offset
Asia/Tokyo	UTC+9
Asia/Kuala_Lumpur	UTC+8
America/New_York	UTC-5 / UTC-4 (DST)
America/Los_Angeles	UTC-8 / UTC-7 (DST)
Europe/London	UTC+0 / UTC+1 (DST)
UTC	UTC+0

tip

The project timezone (set via updateProjectTimezone) is used as the default when creating schedules through the UI. When creating schedules via the API, always specify the timezone explicitly.

---

Example: Create a Schedule

mutation {
  createJobSchedule(
    projectId: "personal-youruser"
    input: {
      name: "Daily report"
      cronExpression: "0 9 * * *"
      timezone: "Asia/Tokyo"
      jobInput: {
        agentName: "report-agent"
        command: "generate-daily-report"
      }
      enabled: true
    }
  ) {
    id
    name
    cronExpression
    timezone
    enabled
    nextFireTime
  }
}

Example: Toggle a Schedule

mutation {
  toggleJobSchedule(id: 42, enabled: false)
}

Example: Run Immediately

mutation {
  runJobScheduleNow(id: 42) {
    id
    status
  }
}