Skip to main content

Replace report schedules

PUT https://api.rollstack.com/public/v1/reports/{id}/schedules

Replaces the schedules of a report of any type, at most 10; an empty list removes them all. Only its editors may. A scheduled run updates the whole report: an AI update on a SlideDeck report, and a refresh of every sync on a report of another type, or only the syncIds a schedule names. Schedules are checked every 15 minutes, so a cron that fires more often still runs at most once per 15 minutes.

Requires the slide_decks:write scope.

Operation ID: updateReportSchedules.

Path parameters

  • id (string, required): The report to act on, of any type, by its id from listReports or createReport. You can also copy it from the report's link in Rollstack (appUrl): it's the part right after /slides/ or /destinations/.

Headers

  • Idempotency-Key (string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.

Request body, required

application/json

  • schedules (array of object, required): The report's new schedules. They replace all of its current schedules, so read them with getReportSchedules first and include any you want to keep, with their syncIds; send an empty list to remove them all. When several schedules fall at the same time, the report runs once. Up to 10.
    • frequency (string, required): How often the schedule runs. hourly runs every day at each time in selectedTimes, and takes no cronExpression. daily, weekly, monthly and quarterly run whenever cronExpression fires, and take no selectedTimes. For those, the frequency doesn't change when the report runs, but the app uses it to describe and edit the schedule, so pick the one that matches your cron expression. One of hourly, daily, weekly, monthly, quarterly.
    • cronExpression (string): When a daily, weekly, monthly or quarterly schedule runs: a five-field cron expression (minute, hour, day of month, month, day of week) in the schedule's timezone, such as 0 9 * * 1 for every Monday at 9:00, or 0 9 L * * for 9:00 on the last day of each month. Required for those frequencies; omit it for hourly. Rollstack checks schedules every 15 minutes, so the minute field must include 0, 15, 30 or 45, and runs at other minutes are skipped. At most 100 characters. Example: 0 9 * * 1.
    • selectedTimes (array of string): The times of day an hourly schedule runs, every day, as 24-hour HH:mm in the schedule's timezone, such as 09:00 or 13:45. Required for hourly; omit it for other frequencies. Each time must be on the quarter hour (:00, :15, :30 or :45). From 1 to 96 times.
    • startDate (string (date-time), required): When the schedule starts: it never runs the report before this date and time. This is a local date and time in the schedule's timezone, written as if it were UTC: 2026-11-02T09:00:00Z means 9:00 on November 2, 2026 in that timezone, not 9:00 UTC. For frequencies other than hourly, set it to the date and time of the first run: the app shows its time as the schedule's time, and when someone changes the schedule's frequency or days there, it rebuilds cronExpression at that time. Example: 2026-11-02T09:00:00Z.
    • endDate (string (date-time) or null): When the schedule ends: it never runs the report after this date and time. Omit it or pass null for a schedule that never ends. Like startDate, this is a local date and time in the schedule's timezone, written as if it were UTC. Must be later than startDate. Set it later than the last run you want: a run at exactly this time may be skipped. Defaults to null. Example: 2027-11-02T09:00:00Z.
    • timezone (string, required): The timezone the schedule runs in. Its run times (cronExpression or selectedTimes), startDate and endDate are all local times in this timezone, so a schedule set for 9:00 keeps running at 9:00 local time when daylight saving time starts or ends. Given as an IANA timezone name, such as America/New_York. UTC offsets such as +05:30 aren't accepted. Example: America/New_York.
    • syncIds (array of string (uuid) or null): The syncs, from listReportSyncs, that the schedule updates on a report other than a SlideDeck. null when it updates the whole report, which a slide deck always does. Omit it or pass null to update the whole report. Each id must be a sync of this report, so it only works on a report other than a SlideDeck. Keep the syncIds getReportSchedules returns for schedules you don't mean to change. A sync deleted later is skipped, so a schedule whose syncs are all gone updates nothing. Defaults to null.

Response 200

Success

application/json: array of object

  • id (string, required): Unique identifier for the schedule. updateReportSchedules replaces every schedule, so the ids change each time you call it.
  • frequency (string, required): How often the schedule runs. hourly runs every day at each time in selectedTimes. daily, weekly, monthly and quarterly run whenever cronExpression fires; those made in the app run every day, on chosen weekdays, on chosen days of the month, or every three months, respectively. yearly can't be set through the API or the app, and also runs on cronExpression. One of daily, weekly, monthly, quarterly, hourly, yearly.
  • cronExpression (string, required): When the schedule runs, as a five-field cron expression (minute, hour, day of month, month, day of week) in the schedule's timezone. For an hourly schedule, Rollstack generates it from selectedTimes and runs the report at those times instead. Monthly schedules made in the app can use L and #, such as 0 9 L * * (last day of the month) or 0 9 ? * 1#1 (first Monday).
  • selectedTimes (array of string, required): The times of day an hourly schedule runs, every day, as 24-hour HH:mm in the schedule's timezone. Other frequencies don't use it; it's empty on those set through the API.
  • startDate (string (date-time), required): When the schedule starts: it never runs the report before this date and time. This is a local date and time in the schedule's timezone, written as if it were UTC: 2026-11-02T09:00:00Z means 9:00 on November 2, 2026 in that timezone, not 9:00 UTC.
  • endDate (string (date-time) or null, required): When the schedule ends: it never runs the report after this date and time. null if the schedule never ends. Like startDate, this is a local date and time in the schedule's timezone, written as if it were UTC.
  • timezone (string, required): The timezone the schedule runs in. Its run times (cronExpression or selectedTimes), startDate and endDate are all local times in this timezone, so a schedule set for 9:00 keeps running at 9:00 local time when daylight saving time starts or ends. Given as an IANA timezone name, such as America/New_York.
  • syncIds (array of string or null, required): The syncs, from listReportSyncs, that the schedule updates on a report other than a SlideDeck. null when it updates the whole report, which a slide deck always does.
  • nextRunAt (string (date-time) or null, required): When the schedule will next run the report. null if it has no runs left before its endDate. Unlike startDate and endDate, this is an actual UTC time.