## 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 Parameters

- `interval: number`

  How many `unit`s pass between runs — the `2` in "every 2 weeks".

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

  - `"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.

- `dayOfWeek: optional number`

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

- `month: optional number`

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

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

### Returns

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

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

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

  - `queryHasParameters: boolean`

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

### Example

```http
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"
        }'
```

#### Response

```json
{
  "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
}
```