Skip to main content

Schedules

When a report updates on its own. Each schedule starts a run of the whole report at the times it sets, in its timezone: hourly at chosen times of day, or on a cron expression for daily, weekly, monthly, quarterly and yearly ones.

A report has up to 10 schedules, replaced together. Schedules are checked every 15 minutes, so a cron expression must run at minute 0, 15, 30 or 45. To give up to 50 reports the same schedules, use batchUpdateReportSchedules.

List schedules

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

The schedules of a report of any type, with the syncs each updates and when each runs next, or null for one that never runs again. Read them before updateReportSchedules, which replaces them all.

Requires the slide_decks:read scope.

Operation ID: getReportSchedules.

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/.

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.

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.

Replace schedules of reports in a batch

POST https://api.rollstack.com/public/v1/reports/batch-update-schedules

Gives up to 50 reports of any type the same schedules, replacing all of each report's current ones, as updateReportSchedules does for one; an empty list removes them all. Each schedule updates its whole report. Only the reports' editors may. Answers one result per report, each naming its id, with its new schedules: a report you can't edit fails on its own and keeps its schedules, while the others are still changed.

Requires the slide_decks:write scope.

Operation ID: batchUpdateReportSchedules.

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

  • ids (array of string, required): The reports to act on, of any type, by their id from listReports. From 1 to 50 ids; an id listed twice is acted on once.
  • schedules (array of object, required): The new schedules of every report. They replace all of each report's current schedules; send an empty list to remove them all. Each schedule updates the whole report: to update only some syncs of a report, set its schedules with updateReportSchedules. 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.

Response 200

Success

application/json

  • results (array of object, required): One result per report, each naming its id.
    • When status is done
      • id (string, required): The report, by its id from ids.
      • status (done, required): The call succeeded on this report.
      • result (array of object, required): The report's schedules, as getReportSchedules answers them.
        • 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.
    • When status is failed
      • id (string, required): The report, by its id from ids.
      • status (failed, required): The call failed on this report and changed nothing on it. The other reports are unaffected.
      • error (object, required): Why this report failed, as the endpoint for one report would answer. Retry only these reports.
        • code (string, required): A stable, machine-readable code for the error, such as api-key-missing-scope or data-validation-error. Use it, rather than message, to handle specific errors in your code.
        • message (string, required): A human-readable explanation of what went wrong, to log or show to people. When the request's path parameters, query or body are invalid (data-validation-error), it lists each invalid field by its path, with the problem, such as body.emails.0: Invalid email address.
        • statusCode (number, required): The HTTP status the same call on this report alone would answer, such as 404 or 403.