> ## Documentation Index > Fetch the complete documentation index at: https://docs.omni.co/llms.txt > Use this file to discover all available pages before exploring further. # Create schedule > Creates 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) ## OpenAPI ````yaml /api/openapi.yaml post /v1/schedules openapi: 3.1.0 info: title: Omni API description: > The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. version: 1.0.0 contact: name: Omni Support url: https://docs.omni.co servers: - url: https://{instance}.omniapp.co/api description: Production variables: instance: default: blobsrus description: Your production Omni instance subdomain - url: https://{instance}.playground.exploreomni.dev/api description: Playground variables: instance: default: blobsrus description: Your playground Omni instance subdomain security: - bearerAuth: [] - orgApiKey: [] tags: - name: AI description: AI-powered query generation - name: API Tokens description: >- Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth grants) - name: Connections description: Manage database connections - name: Connection environments description: Manage connection environments database connections - name: Content description: Unified content retrieval (documents and folders) - name: Content migration description: Export and import dashboards - name: Content validator description: Validate content against models and perform find/replace operations - name: Dashboard downloads description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files - name: Dashboard filters and controls description: Read and update dashboard filter and control default values - name: dbt description: Manage dbt configuration for connections - name: Documents description: Create, retrieve, and manage documents - name: Document favorites description: Favorite and unfavorite documents - name: Document labels description: Apply and manage labels on documents - name: Document permissions description: Manage document-level access - name: Labels description: > Manage labels in an organization. Labels can be applied to documents and folders to help organize and categorize content. **Label types:** - **Basic labels**: Can be created and managed by any user - **Verified labels**: Indicate curated or officially sanctioned content. Admin-only. - **Homepage labels**: Appear on the organization homepage. Admin-only. - name: Folders description: Create and organize content folders - name: Folder permissions description: Manage folder-level access - name: Jobs description: Check status of asynchronous jobs - name: Models description: Create and manage data models - name: Model branches description: Manage model branches and merge changes - name: Model git configuration description: Manage git configuration for shared models - name: Queries description: Execute workbook queries - name: Schedules description: Create and manage scheduled tasks - name: Schedule recipients description: Manage schedule recipients - name: Schema refresh schedules description: Manage automated schema refresh schedules for connections - name: Topics description: Retrieve topic information from models - name: Uploads description: Manage file uploads - name: Users description: Manage users - name: User attributes description: Manage user attribute definitions - name: User groups description: Manage user groups - name: User model roles description: Manage model and connection role assignments for users - name: User group model roles description: Manage model and connection role assignments for user groups - name: Uploads description: Manage CSV and spreadsheet uploads paths: /v1/schedules: post: tags: - Schedules summary: Create schedule description: > Creates 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) operationId: createSchedule parameters: - name: userId in: query schema: type: string format: uuid description: > **Only supported when using an Organization API key.** The membership ID of the user who should own the schedule. **Note**: This value is the **membership ID**, not the user ID. Use the [List users](/api/users/list-users) endpoint to retrieve membership IDs. When using an Organization API key: - If `userId` is provided, the schedule is owned by the specified user - If `userId` is not provided, the schedule is owned by the organization Attempting to use a Personal Access Token (PAT) with this parameter will result in a `403 Forbidden` error. When using a PAT, the schedule owner will be the creator of the PAT. requestBody: required: true content: application/json: schema: type: object required: - identifier - name - schedule - timezone - format - destinationType properties: identifier: type: string description: > 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: type: string description: The name of the task. schedule: type: string description: > 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). timezone: type: string description: > 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: type: string enum: - csv - link_only - json - pdf - png - xlsx description: | The output format of the schedule. destinationType: type: string enum: - webhook - email - sftp - slack - s3 description: > The destination where the task's output should be delivered. **Note**: If using `slack`, you must connect a Slack workspace to Omni first. filterConfig: type: object description: > 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: type: string enum: - RESULTS_PRESENT - RESULTS_CHANGED - RESULTS_MISSING - RESULTS_UNCHANGED description: > **Required if `conditionQueryMapKey` is provided.** Defines the type of condition to use for alerts. conditionQueryMapKey: type: string description: > **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: type: string description: > 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: type: boolean default: false description: > If `true`, stop the entire job if any queries included in the task fail. testNow: type: boolean default: false description: > If `true`, run the task immediately instead of scheduling. Not supported for `RESULTS_CHANGED` alert conditions or `s3` destinations. hideTitle: type: boolean default: false description: > **Compatible with `pdf` and `png` formats.** If `true`, the content's title will be hidden in the task's output. hideHiddenFields: type: boolean default: false description: > **Compatible with `csv` and `xlsx` formats.** If `true`, fields marked as `hidden` won't be displayed in the task's output. enableFormatting: type: boolean default: false description: > **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: type: boolean default: false description: > **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: type: integer description: > **Compatible with `csv`, `json`, and `xlsx` formats.** Used with `overrideRowLimit`. Specifies the maximum number of rows. showContentLink: type: boolean default: true description: > **Compatible with all formats except `link_only`.** If `true`, a link to the content will be shown in the task's output. showFilters: type: boolean default: true description: > **Compatible with all formats except `link_only` and `csv`.** If `true`, filters will be shown in the task's output. expandTablesToShowAllRows: type: boolean default: false description: > **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: type: string enum: - a3 - a4 - letter - legal - fit_page - tabloid description: > **Compatible with `pdf` format.** Defines the paper format (size) of the resulting PDF. The `fit_page` option cannot be used if `expandTablesToShowAllRows: true`. paperOrientation: type: string enum: - portrait - landscape description: > **Compatible with `pdf` format.** Defines the paper orientation of the resulting PDF. singleColumnLayout: type: boolean default: false description: > **Compatible with `pdf` and `png` formats.** If `true`, dashboard tiles will be arranged into a single vertical column. url: type: string description: > **Required if `destinationType: webhook`.** A webhook URL. Must be a valid HTTP/HTTPS URL. recipients: oneOf: - type: string - type: array items: type: string description: > **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"]`) subject: type: string description: > **Required if `destinationType: email`.** Email subject line. textBody: type: string description: > **Applicable to email and Slack destinations.** Custom message text included with the delivery. slackRecipientType: type: string enum: - channel - users description: > **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: type: boolean default: false description: > **Applicable to email destinations.** If `true`, send individual emails to each recipient. address: type: string description: > **Required if `destinationType: sftp`.** SFTP server address. port: type: integer description: | **Required if `destinationType: sftp`.** SFTP port. username: type: string description: | **Required if `destinationType: sftp`.** SFTP username. path: type: string description: | **Required if `destinationType: sftp`.** Remote file path. passwordUnencrypted: type: string description: | **Applicable to SFTP destinations.** SFTP password. bucketName: type: string description: > **Required if `destinationType: s3`.** The name of the target S3 bucket. Must be 3-63 characters, lowercase letters, numbers, hyphens, and periods only. example: my-reports-bucket region: type: string description: > **Required if `destinationType: s3`.** The AWS region of the S3 bucket (e.g., `us-east-1`). example: us-east-1 roleArn: type: string description: > **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. example: arn:aws:iam::123456789012:role/OmniS3DeliveryRole keyPrefix: type: string description: > **Applicable to S3 destinations.** Folder path prefix for the uploaded file (e.g., `reports/daily/`). Must not contain path traversal sequences. example: reports/daily/ filename: type: string description: > **Applicable to S3 destinations.** Filename template (without extension) using Mustache syntax. Supported variables: `{{currentDate}}`, `{{currentTime}}`, `{{currentYear}}`, `{{currentMonth}}`, `{{currentDay}}`, `{{yesterdayDate}}`, `{{timeZone}}`, `{{entityName}}`, `{{format}}`, `{{scheduledTaskName}}`. example: '{{scheduledTaskName}}_{{currentDate}}' examples: Webhook: summary: Webhook destination value: identifier: 12db1a0a name: My Webhook schedule schedule: 0 9 ? * * * timezone: UTC format: json destinationType: webhook url: https://webhooksrus.com/1234566 Email: summary: Email destination value: identifier: 12db1a0a name: My Email schedule schedule: 0 9 ? * * * timezone: UTC format: pdf destinationType: email paperFormat: legal expandTablesToShowAllRows: true paperOrientation: landscape recipients: - user1@example.com - user2@example.com subject: Daily Sales report textBody: Here are the daily sales! fanOut: false SFTP: summary: SFTP destination value: identifier: 12db1a0a name: My SFTP schedule schedule: 0 9 ? * * * timezone: UTC format: xlsx destinationType: sftp address: sftp.example.com port: 22 username: sftpuser passwordUnencrypted: password123 Slack channel: summary: Slack channel destination value: identifier: 12db1a0a name: Weekly Report schedule: 0 9 ? * MON * timezone: America/New_York format: pdf destinationType: slack recipients: C01234567 slackRecipientType: channel textBody: Here is your weekly report! Slack users: summary: Slack users destination value: identifier: 12db1a0a name: Sales Team Report schedule: 0 9 ? * * * timezone: America/New_York format: pdf destinationType: slack recipients: - U11111111 - U22222222 slackRecipientType: users textBody: Your daily sales report Amazon S3: summary: Amazon S3 destination value: identifier: 12db1a0a name: Daily Export to S3 schedule: 0 9 ? * * * timezone: UTC format: csv destinationType: s3 bucketName: my-reports-bucket region: us-east-1 roleArn: arn:aws:iam::123456789012:role/OmniS3DeliveryRole keyPrefix: reports/daily/ filename: '{{entityName}}-{{currentDate}}' Filters and formatting: summary: Filters and formatting value: identifier: dashboard-abc123 name: Weekly Regional Report schedule: 0 0 ? * MON * timezone: UTC format: pdf destinationType: email recipients: - iamagoodblob@blobsrus.com - managerblob@blobsrus.com subject: Weekly Regional Report filterConfig: region: kind: EQ left_side: US type: string hideTitle: true Alert condition: summary: Alert condition value: identifier: dashboard-abc123 name: Data Alert Webhook schedule: 0 */6 * * ? * timezone: UTC format: json destinationType: webhook url: https://api.example.com/webhook conditionType: RESULTS_PRESENT conditionQueryMapKey: '1' queryIdentifierMapKey: '1' overrideRowLimit: true maxRowLimit: 1000 Test delivery: summary: Test delivery value: identifier: dashboard-abc123 name: Test Delivery schedule: 0 0 1 1 ? 2099 timezone: UTC format: pdf destinationType: email recipients: - iamagoodblob@blobsrus.com subject: Test Delivery testNow: true responses: '200': description: Schedule created successfully content: application/json: schema: type: object properties: id: type: string format: uuid description: The ID of the created schedule. message: type: string example: Successfully created schedule description: A success message. delivererRoleArn: type: string description: > **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: type: string description: > **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. examples: Default: summary: Default response value: id: 12db1a0a message: Successfully created schedule Amazon S3: summary: Amazon S3 destination value: id: 12db1a0a message: Successfully created schedule delivererRoleArn: arn:aws:iam::123456789012:role/OmniS3DeliveryRole externalId: '400': description: > 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: . Available dashboard filter keys are: , , ....` - `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` content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: > Forbidden Possible error messages: - `Personal access tokens cannot create schedules on behalf of other users` content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: | Not Found Possible error messages: - `Document with identifier "" not found` content: application/json: schema: $ref: '#/components/schemas/Error' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: Error: type: object properties: error: type: string description: HTTP response code for the error example: message: type: string description: Detailed error description example: responses: MethodNotAllowed: description: Method Not Allowed - Invalid HTTP method for this endpoint content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too Many Requests - Rate limit exceeded (60 requests/minute) content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Can be either an [Organization API Key](/api/authentication#organization-api-keys) or [Personal Access Token (PAT)](/api/authentication#personal-access-tokens-pat). Include in the `Authorization` header as: `Bearer YOUR_TOKEN` orgApiKey: type: http scheme: bearer bearerFormat: JWT description: > Requires an [Organization API Key](/api/authentication#organization-api-keys). Personal Access Tokens (PATs) are not supported for this endpoint. Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY` ````