---
title: "Create a schedule"
method: POST
path: "/schedules"
tags: ["Schedules"]
---

# Create a schedule

`POST /schedules`

## Request

- Base URL: `https://saturnsql.com/api`
- URL: `https://saturnsql.com/api/schedules`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Schedules a saved query to run on a cron cadence and export its result to ONE destination — Google Sheets (spreadsheetId/spreadsheetName + sheetName + startCell) OR Slack (slackChannelId). Scheduling is plan-gated. Available to API keys with both the `write` and `execute` scopes, since a schedule runs its saved query's SQL.

## Request body

- object
  - `savedQueryId` string, required
  - `cronExpression` string, required: 5-field cron expression, e.g. '0 7 * * *' for daily 7am
  - `timezone` string: IANA timezone, default UTC
  - `spreadsheetId` string: Google Sheets destination (existing sheet)
  - `spreadsheetName` string: Or create a new spreadsheet by name (with createNew: true)
  - `sheetName` string
  - `startCell` string: A1 notation, default A1
  - `includeHeaders` boolean: Default true
  - `createNew` boolean: Create a new spreadsheet named spreadsheetName
  - `slackChannelId` string, nullable: Slack destination (instead of Sheets)
  - `slackChannelName` string, nullable
  - `slackMessageTemplate` string, nullable

## Response `201`

Created

- Schedule
  - `id` string
  - `savedQueryId` string
  - `cronExpression` string: 5-field cron expression evaluated in `timezone`, e.g. '0 9 * * 1' for Monday 9am
  - `timezone` string: IANA timezone, e.g. America/New_York
  - `startCell` string: A1 notation anchor for the export
  - `includeHeaders` boolean
  - `enabled` boolean
  - `nextRunAt` string, date-time, nullable
  - `lastRunAt` string, date-time, nullable
  - `lastError` string, nullable
  - `destinationType` 'sheets' | 'slack', nullable
  - `spreadsheetId` string, nullable
  - `spreadsheetName` string, nullable
  - `sheetName` string, nullable
  - `slackChannelId` string, nullable
  - `slackChannelName` string, nullable

## Other responses

- `400`: Validation failed / more than one destination / invalid cron expression
- `401`: Bad or missing credentials
- `403`: Scheduling not available on plan
- `409`: A schedule already exists for this query

---

[API](https://skmtc.dev/saturnsql/apis/saturnsql-api.md) · [All operations](https://skmtc.dev/saturnsql/apis/saturnsql-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saturnsql/apis/saturnsql-api/revisions/90a3e54ad115?raw)