Preview a Report Schedule

POST/print-mail/v1/reports/schedule_previews

Work out when a schedule would actually run, without saving anything. Takes the same fields as the schedule on a report, plus an optional sqlQuery so you can check whether that query is schedulable at all (a parameterized query is not).

Body ParametersJSONExpand Collapse

interval: number

How many units pass between runs — the 2 in “every 2 weeks”.

formatint32

minimum1

time: string

The 24-hour HH:mm time of day the report runs, in America/Toronto.

unit: "h" or "d" or "w" or 2 more

The cadence units a report schedule may use: hour, day, week, month, or year.

One of the following:

"h"

"d"

"w"

"m"

"y"

dayOfMonth: optional number

Monthly and yearly schedules only. Monthly schedules are capped at 28 so a run never skips a short month.

formatint32

minimum1

maximum31

dayOfWeek: optional number

Weekly schedules only. 0 is Sunday through 6 for Saturday.

formatint32

minimum0

maximum6

month: optional number

Yearly schedules only. 0 is January through 11 for December.

formatint32

minimum0

maximum11

notificationEmails: optional array of string

Up to 10 addresses to email when a run finishes. Each must belong to a user in the same organization as the report; others are skipped. Omit or pass an empty array to send no email.

sqlQuery: optional string

The query the schedule would run against. Supplying it flags a parameterized query as unschedulable via queryHasParameters. It is only inspected — creating or updating a report always uses the report’s own sqlQuery.

ReturnsExpand Collapse

SchedulePreview object { dayOfMonth, dayOfMonthOptions, description, 4 more }

The cadence PostGrid derived from a schedule, returned without saving anything. Useful for confirming when a schedule would actually run.

dayOfMonth: number

The day of the month the schedule resolved to, clamped to a day that exists.

formatint32

dayOfMonthOptions: array of object { label, value }

The days of the month this cadence may be anchored to, with display labels.

label: string

The day as an ordinal, for example 15th.

value: number

The day of the month.

formatint32

description: string

The cadence in words, for example Every 2 weeks on Monday at 9:00 AM (America/Toronto).

firstRunLabel: string

The first run as an absolute instant, for example Monday, June 15, 2026 at 9:00 AM.

frequency: string

The cadence as a number + unit, for example 1h or 2d.

nextRun: string

When the report would run next.

formatdate-time

queryHasParameters: boolean

True if the supplied sqlQuery uses parameters, which makes it unschedulable.

Preview a Report Schedule

curl https://api.postgrid.com/print-mail/v1/reports/schedule_previews \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $POSTGRID_PRINT_MAIL_API_KEY" \
    -d '{
          "interval": 1,
          "time": "20:29",
          "unit": "h"
        }'

{
  "frequency": "1w",
  "nextRun": "2026-06-15T13:00:00Z",
  "description": "Every week on Monday at 9:00 AM (America/Toronto)",
  "firstRunLabel": "Monday, June 15, 2026 at 9:00 AM",
  "dayOfMonth": 1,
  "dayOfMonthOptions": [
    {
      "value": 1,
      "label": "1st"
    },
    {
      "value": 2,
      "label": "2nd"
    }
  ],
  "queryHasParameters": false
}

Returns Examples

{
  "frequency": "1w",
  "nextRun": "2026-06-15T13:00:00Z",
  "description": "Every week on Monday at 9:00 AM (America/Toronto)",
  "firstRunLabel": "Monday, June 15, 2026 at 9:00 AM",
  "dayOfMonth": 1,
  "dayOfMonthOptions": [
    {
      "value": 1,
      "label": "1st"
    },
    {
      "value": 2,
      "label": "2nd"
    }
  ],
  "queryHasParameters": false
}