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

# Create schedule

`POST /v1/schedules`

Create a scheduled task for the specified dashboard. Supports applying filters and formatting, creating alert conditions, and triggering test deliveries.

Supports the following destinations:

- [**Email**](/share/deliveries/email)
- [**Slack**](/share/deliveries/slack) - **Note**: A Slack workspace must already be connected to Omni to use this destination type.
- [**SFTP**](/share/deliveries/sftp)
- [**Webhook**](/share/deliveries/webhooks)
- [**Amazon S3**](/share/deliveries/amazon-s3)

## Query parameters

- `userId` string, uuid

## Request body

- object
  - `identifier` string, required — The ID of the dashboard where the task will be created. This can be retrieved by: - **Opening the document settings** - Navigate to **File > Document settings** in the dashboard and then click **Settings**. The **Identifier** field contains the dashboard ID. - **Using the dashboard's URL** - The string after `/dashboards` is the dashboard's ID; for example: `https://myorg.omniapp.co/dashboards/12db1a0a`
  - `name` string, required — The name of the task.
  - `schedule` string, required — A cron expression defining when the schedule will run, in [Amazon Web Services (AWS) Cloudwatch syntax](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html). **Note**: Delivery times are approximate and will happen within 15 minutes of the specified schedule run time.
  - `timezone` string, required — The IANA timezone where the task should run, such as `Asia/Dubai`. Refer to the [`TZ` column in this IANA.org timezone description file](https://data.iana.org/time-zones/tzdb-2021a/zone1970.tab) for a list of accepted values.
  - `format` 'csv' | 'link_only' | 'json' | 'pdf' | 'png' | 'xlsx', required — The output format of the schedule.
  - `destinationType` 'webhook' | 'email' | 'sftp' | 'slack' | 's3', required — The destination where the task's output should be delivered. **Note**: If using `slack`, you must connect a Slack workspace to Omni first.
  - `filterConfig` object — An object specifying the filter conditions to apply to the task. The filter key specified must already exist in the dashboard. If the dashboard doesn't have any filters configured, filters can't be used in the task. Use the [Get dashboard filters and controls endpoint](/api/dashboard-filters/get-dashboard-filters-and-controls) to retrieve filter configuration objects. **Note**: Filter keys are case-sensitive and must match exactly.
  - `conditionType` 'RESULTS_PRESENT' | 'RESULTS_CHANGED' | 'RESULTS_MISSING' | 'RESULTS_UNCHANGED' — **Required if `conditionQueryMapKey` is provided.** Defines the type of condition to use for alerts.
  - `conditionQueryMapKey` string — **Required if `conditionType` is provided.** The ID of the query to monitor for triggering an alert. Must reference a valid query in the dashboard.
  - `queryIdentifierMapKey` string — The ID of the query to include in a single tile task. Must reference a valid query in the dashboard. **Required for:** - `format: json` with `enableFormatting: true` - `format: xlsx` with `overrideRowLimit: true`
  - `killJobsOnFailure` boolean — If `true`, stop the entire job if any queries included in the task fail.
  - `testNow` boolean — If `true`, run the task immediately instead of scheduling. Not supported for `RESULTS_CHANGED` alert conditions or `s3` destinations.
  - `hideTitle` boolean — **Compatible with `pdf` and `png` formats.** If `true`, the content's title will be hidden in the task's output.
  - `hideHiddenFields` boolean — **Compatible with `csv` and `xlsx` formats.** If `true`, fields marked as `hidden` won't be displayed in the task's output.
  - `enableFormatting` boolean — **Compatible with `csv`, `xlsx`, and `json` formats.** If `true`, number and date formatting will be preserved in the task's output. If `true` for `json` format, `queryIdentifierMapKey` is required.
  - `overrideRowLimit` boolean — **Compatible with `csv`, `json`, and `xlsx` formats.** If `true`, the default row limit will be overridden. If `true` for `json` and `xlsx` formats, a `queryIdentifierMapKey` is required.
  - `maxRowLimit` integer — **Compatible with `csv`, `json`, and `xlsx` formats.** Used with `overrideRowLimit`. Specifies the maximum number of rows.
  - `showContentLink` boolean — **Compatible with all formats except `link_only`.** If `true`, a link to the content will be shown in the task's output.
  - `showFilters` boolean — **Compatible with all formats except `link_only` and `csv`.** If `true`, filters will be shown in the task's output.
  - `expandTablesToShowAllRows` boolean — **Compatible with `pdf` and `png` formats.** If `true`, up to 1,000 rows in table visualizations will be included in the delivery. This parameter cannot be used when `paperFormat: fit_page`.
  - `paperFormat` 'a3' | 'a4' | 'letter' | 'legal' | 'fit_page' | 'tabloid' — **Compatible with `pdf` format.** Defines the paper format (size) of the resulting PDF. The `fit_page` option cannot be used if `expandTablesToShowAllRows: true`.
  - `paperOrientation` 'portrait' | 'landscape' — **Compatible with `pdf` format.** Defines the paper orientation of the resulting PDF.
  - `singleColumnLayout` boolean — **Compatible with `pdf` and `png` formats.** If `true`, dashboard tiles will be arranged into a single vertical column.
  - `url` string — **Required if `destinationType: webhook`.** A webhook URL. Must be a valid HTTP/HTTPS URL.
  - `recipients` union — **Required if `destinationType: email` or `destinationType: slack`.** For **email** destinations: An array of strings, each specifying a valid email address. For **Slack** destinations: Channel or user IDs. Accepts either a string or array format: - **Channels** can be a single channel ID (`"C01234567"`) or an array with exactly **one** channel ID (`["C01234567"]`). Additionally: - **For private channels**, invite the Omni Slackbot to the channel first - Only one Slack channel is supported per schedule. Multiple channels will return a 400 error. - **Users** can be a string of comma-separated user IDs (`"U111,U222"`) or an array of user IDs (`["U111", "U222"]`)
    - string
    - string[]
  - `subject` string — **Required if `destinationType: email`.** Email subject line.
  - `textBody` string — **Applicable to email and Slack destinations.** Custom message text included with the delivery.
  - `slackRecipientType` 'channel' | 'users' — **Required if `destinationType: slack`.** Specifies whether recipients are a channel or individual users. - `channel`: Deliver to a Slack channel. If the channel is private, you'll also need to invite the Omni Slackbot to the channel. - `users`: Deliver to individual Slack users
  - `fanOut` boolean — **Applicable to email destinations.** If `true`, send individual emails to each recipient.
  - `address` string — **Required if `destinationType: sftp`.** SFTP server address.
  - `port` integer — **Required if `destinationType: sftp`.** SFTP port.
  - `username` string — **Required if `destinationType: sftp`.** SFTP username.
  - `path` string — **Required if `destinationType: sftp`.** Remote file path.
  - `passwordUnencrypted` string — **Applicable to SFTP destinations.** SFTP password.
  - `bucketName` string — **Required if `destinationType: s3`.** The name of the target S3 bucket. Must be 3-63 characters, lowercase letters, numbers, hyphens, and periods only.
  - `region` string — **Required if `destinationType: s3`.** The AWS region of the S3 bucket (e.g., `us-east-1`).
  - `roleArn` string — **Required if `destinationType: s3`.** The ARN of the IAM role in the customer's AWS account that grants Omni write access to the S3 bucket.
  - `keyPrefix` string — **Applicable to S3 destinations.** Folder path prefix for the uploaded file (e.g., `reports/daily/`). Must not contain path traversal sequences.
  - `filename` string — **Applicable to S3 destinations.** Filename template (without extension) using Mustache syntax. Supported variables: `{{currentDate}}`, `{{currentTime}}`, `{{currentYear}}`, `{{currentMonth}}`, `{{currentDay}}`, `{{yesterdayDate}}`, `{{timeZone}}`, `{{entityName}}`, `{{format}}`, `{{scheduledTaskName}}`.

## Response `200`

Schedule created successfully

- object
  - `id` string, uuid — The ID of the created schedule.
  - `message` string — A success message.
  - `delivererRoleArn` string — **S3 destinations only.** The ARN of Omni's deliverer IAM role. The customer uses this as the `Principal` in their IAM trust policy to allow Omni to assume their role.
  - `externalId` string — **S3 destinations only.** The organization ID, used as the external ID in the IAM trust policy `sts:ExternalId` condition. This value is the same for all S3 destinations in the organization.

## Other responses

- `400` — Bad Request Possible error messages: - `Analyses do not support dashboards.` - `Document does not have a dashboard` - `schedule: Schedule is an invalid cron expression` - `timezone: Time zone must be IANA valid.` - `hideTitle can only be used with PDF or PNG formats` - `Invalid filter keys found in schedule configuration: <filterKey>. Available dashboard filter keys are: <key1>, <key2>, ....` - `Test delivery not supported for condition type RESULTS_CHANGED` - `Print options are not supported for this format` - `Single column layout and table expansion options are not supported for FIT_PAGE format.` - `Must provide both a trigger query and an alert condition type` - `slackRecipientType is required for Slack destinations` - `Only one Slack channel is supported per schedule` - `Organization does not have a Slack credential configured` - `Test delivery not supported for S3 destinations` - `Invalid bucket name` - `Invalid role ARN` - `Invalid region` - `Key prefix contains invalid path traversal`
- `403` — Forbidden Possible error messages: - `Personal access tokens cannot create schedules on behalf of other users`
- `404` — Not Found Possible error messages: - `Document with identifier "<dashboardId>" not found`
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)
- `500` — Internal Server Error

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)