Schedules
Chronos offers two ways to define when a job should run: a user-friendly daily schedule picker and standard cron expressions. Both can be used through the REST API and the Gluesync UI.
Scheduling Options
User-Friendly Daily Schedule Format
Chronos supports a user-friendly schedule format that doesn’t require knowledge of cron expressions:
{
"schedule": {
"days_of_week": ["monday", "wednesday", "friday"],
"hour": 8,
"minute": 30
}
}Parameters:
-
days_of_week: Array of days when the job should run. Valid values are: "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday". An empty array means every day. -
hour: Hour of the day (0-23) -
minute: Minute of the hour (0-59)
Examples:
-
Every day at 8:30 AM:
{"days_of_week": [], "hour": 8, "minute": 30} -
Every Monday, Wednesday, and Friday at 8:30 AM:
{"days_of_week": ["monday", "wednesday", "friday"], "hour": 8, "minute": 30} -
Every weekend at midnight:
{"days_of_week": ["saturday", "sunday"], "hour": 0, "minute": 0}
This is the same format used by the Gluesync UI scheduler form: select the days of the week, enter the time in hh:mm format, and pick AM or PM.
Cron Expression Format
Chronos also supports standard cron expressions for more advanced scheduling needs:
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *Examples:
-
0 * * * *- Run once every hour -
0 0 * * *- Run once a day at midnight -
0 0 * * 0- Run once a week on Sunday at midnight -
0 0 1 * *- Run once a month on the 1st at midnight
Use cron expressions when you need more flexibility than the daily picker provides, such as monthly schedules, specific day-of-month rules, or non-daily intervals.
Creating a Scheduled Job
Jobs can be created via the REST API:
POST /api/jobs
{
"name": "Monday-Wednesday-Friday Job",
"description": "Runs on specific days at 8:30 AM",
"task_type": "entity_snapshot",
"schedule": {
"days_of_week": ["monday", "wednesday", "friday"],
"hour": 8,
"minute": 30
},
"pipeline_id": "pipeline-123",
"entity_id": "entity-456",
"with_snapshot": true,
"enabled": true
}This will automatically be converted to the cron expression 30 8 * * 1,3,5 internally.
The same request using a cron expression looks like this:
POST /api/jobs
{
"name": "Daily at midnight",
"task_type": "pipeline_snapshot",
"cron_expression": "0 0 * * *",
"pipeline_id": "pipeline-123",
"enabled": true
}Running Query Studio queries
Use the Query Studio action type to schedule SQL through an explicitly selected SQL-capable agent. Groups and entities are not used. Selecting a saved query fills agent_id when the query contains one; otherwise select an agent from the agent picker.
At fire time Chronos prefers the live Query Studio saved query from Core Hub and falls back to the SQL snapshot stored on the job. Execution is a Core Hub Query Studio POST (120 second timeout), not a crontab command.
| UI action | API task_type |
|---|---|
Query Studio |
|
The Query Studio task fields follow the same scheduled-job payload as other task types:
{
"task_type": "query_studio",
"pipeline_id": "pipeline-123",
"agent_id": "agent-456",
"query_sql": "SELECT COUNT(*) FROM staging_orders",
"saved_query_id": "saved-query-789",
"query_read_only": true
}| Field | Required | Description |
|---|---|---|
|
Yes |
Set to |
|
Yes |
Pipeline in which the Query Studio action runs. |
|
Yes |
Explicit SQL-capable agent that runs the query. |
|
Conditional |
SQL statement to run. Required for custom SQL. When |
|
No |
Selected saved query. Omit for custom SQL. |
|
No |
Whether to enforce read-only execution. Defaults to |
In the UI, selecting I acknowledge this query can modify data sets query_read_only to false.
See Query Studio actions for saved and custom query selection, query_read_only, write acknowledgment, and complete UI steps.
Running published AI agents
Use the ai_agent_run task type to start a published AI agent on a daily or cron schedule. agent_alias is required; pipeline_id is optional and can be empty.
{
"task_type": "ai_agent_run",
"agent_alias": "agent/daily-report",
"agent_input": {
"audience": "operations"
}
}See AI agent runs for input templates, payload allow-listing, event triggers, and loop safeguards.
Timezone Support
All schedules are interpreted in the timezone configured by the TIMEZONE environment variable. The Gluesync UI also lets you select a timezone for the scheduler. Once a job is created, its run times are fixed in that timezone; changing the timezone later does not affect existing jobs.
If no timezone is set, Chronos defaults to UTC.
Repeating Options from the UI
For common scheduling needs, use the simple schedule picker in the Gluesync UI:
Day Selection:
-
A row of checkboxes labeled with day abbreviations (Mon, Tue, Wed, etc.) is displayed
-
Click on each day of the week when you want the task to run
-
Selected days will be highlighted in the interface
Time Configuration:
-
Time input field appears near the day selection
-
Enter the time in
hh:mm12-hour format (e.g.,2:30) -
Select either
AMorPMfrom the dropdown menu -
The time picker will validate your input to ensure it’s in the correct format
-
The scheduled time will be based on the timezone you’ve selected in the top right corner
Example Scenarios:
-
For a task that runs every weekday at 9:00 AM:
-
Check Mon, Tue, Wed, Thu, Fri
-
Enter
09:00in the time field -
For a task that runs on weekends at 11:30 PM:
-
Check Sat, Sun
-
Enter
11:30in the time field and selectPM
Best Practices
-
Use the daily schedule picker for simple recurring jobs
-
Use cron expressions for monthly, hourly, or complex recurrence rules
-
Set a timezone explicitly so jobs run at the expected local time
-
Monitor the
next_runfield to verify your schedule is interpreted correctly -
Test new schedules with a future date before enabling them in production
-
Prefer saved Query Studio queries to make recurring SQL easier to review and update