Skip to main content

Set the schedule timezone

Goal​

You'll set your organization's schedule timezone. It is one IANA zone for the whole organization. Every schedule's cadence is read in it: "every day at 06:00" means 06:00 there, through daylight-saving changes. Every schedule time in the app is shown in it, labelled with the zone's abbreviation (Sep 16, 09:00 EDT). That covers the schedules table, the Validations list and the run calendar, so everyone in the organization reads the same times whatever their browser's zone.

Until an admin sets it, the schedule timezone is UTC.

Prereqs​

  • To change it you need to be an organization admin (super admin). Anyone who can see schedules can open the page and read the zone, but the picker and Save are disabled for them.

Steps​

  1. Open Settings → Scheduling. It sits under Organization. The schedule form's Change it in Settings link opens it too.

  2. Pick the zone. Click the Schedule timezone picker, type to filter (New_York, London, Kolkata), and choose the zone. You can also type any IANA name that isn't in the list and press Enter. The hint under the picker shows the current time there.

  3. Click Save. New schedules now run in this zone, and schedule times across the app are shown in it. Saving doesn't move any existing schedule. If you want to keep UTC, click Save without changing the picker. That records UTC as your choice rather than the default.

  4. Move older schedules, if any. A schedule saved before this setting existed, or through the API with its own timezone, keeps firing in its own zone. The page lists those schedules by zone ("UTC · 2 schedules"). A schedule whose stored zone is blank or isn't a recognised zone is listed as such; it runs in UTC.

    Click Move N schedules to <zone>. A confirmation lists the zones and how many schedules move from each. Click Move N schedules in it to put them all on the organization zone. Each keeps its cadence, and its next run is recalculated in the new zone, so it fires at a different time. For example, a daily 06:00 UTC schedule moved to America/New_York fires at 06:00 New York time from its next run on.

    The button stays disabled until an admin has saved a zone (step 3). That stops a click on the UTC default from moving every schedule to UTC. The audit log records the zone each moved schedule ran in before, so you can see what to put back.

    To move just one schedule instead, open it (pencil icon), tick Run it in <zone> from now on, and save. An editor can do this.

Verify​

  • Settings → Scheduling reads "Set for this organization." and shows your zone.
  • Add schedule on any validation shows your zone, read-only, under the cadence builder.
  • The schedules table's Next run and the Validations → Schedule calendar show times with your zone's abbreviation, and the calendar names the zone above its grid.
  • After Move N schedules, no schedule in the table carries the Not the org timezone badge.

Via the API​

# Read it (any member).
curl -H "Authorization: Bearer dqk_…" \
  https://dq.example.com/api/v1/organizations/<org-id>/schedule-timezone

# Set it (org admin). Add "align_schedules": true to also move every schedule in another zone.
curl -X PUT \
  -H "Authorization: Bearer dqk_…" \
  -H "Content-Type: application/json" \
  https://dq.example.com/api/v1/organizations/<org-id>/schedule-timezone \
  -d '{"timezone": "America/New_York"}'

The response is {"data": {"timezone", "source", "mismatched_schedules", "schedule_timezones", "aligned_schedules"}}. source is default until an admin saves a zone, then org. mismatched_schedules counts the schedules you can see whose stored zone differs, and schedule_timezones counts every schedule you can see by its stored zone, exactly as stored (a blank zone is ""). An unknown zone, or a region name such as America, is a 422. Every change is recorded in the audit log. With align_schedules: true, the audit entry lists every moved schedule with its previous zone (moved_schedules: [{id, old_timezone}]).

Notes​

  • A schedule created through the API without a timezone runs in the organization zone. See Schedules.
  • A schedule is never moved to another zone without you asking. That keeps a change of setting from silently changing when checks run.
  • A schedule whose stored zone is blank or not a recognised zone (a very old or hand-edited schedule) runs in UTC, whatever the organization zone is. The calendar plots it in UTC too. Move it like any other schedule.