openapi: 3.1.0
info:
title: Omni AI Schedules API
description: "The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. \n"
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: Schedules
description: Create and manage scheduled tasks
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)
'
security:
- bearerAuth: []
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).
**Note**: Delivery times are approximate and will happen within 15 minutes of the specified schedule run time.
'
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`.**\n\nFor **email** destinations: An array of strings, each specifying a valid email address.\n\nFor **Slack** destinations: Channel or user IDs. Accepts either a string or array format:\n\n- **Channels** can be a single channel ID (`\"C01234567\"`) or an array with exactly **one** channel ID (`[\"C01234567\"]`). Additionally:\n - **For private channels**, invite the Omni Slackbot to the channel first\n - Only one Slack channel is supported per schedule. Multiple channels will return a 400 error.\n- **Users** can be a string of comma-separated user IDs (`\"U111,U222\"`) or an array of user IDs (`[\"U111\", \"U222\"]`) \n"
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: <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: <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`
'
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 "<dashboardId>" 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'
get:
tags:
- Schedules
summary: List schedules
description: 'Retrieves scheduled tasks. This endpoint supports filtering, sorting, and cursor-based pagination.
To retrieve the recipients for a schedule, use the [List schedule recipients](/api/schedule-recipients/list-schedule-recipients) endpoint.
'
security:
- bearerAuth: []
operationId: listSchedules
parameters:
- name: q
in: query
schema:
type: string
description: 'Search term for filtering schedules by name, dashboard name, or owner name (case-insensitive).
'
- name: status
in: query
schema:
type: string
enum:
- success
- error
- canceled
- none
description: Filter schedules by delivery status.
- name: destination
in: query
schema:
type: string
enum:
- email
- slack
- webhook
- sftp
- s3
description: Filter schedules by destination type.
- name: scheduleType
in: query
schema:
type: string
enum:
- alert
- schedule
description: Filter by schedule type.
- name: contentType
in: query
schema:
type: string
enum:
- dashboard
- single tile
description: Filter schedules by content type.
- name: sortField
in: query
schema:
type: string
default: scheduleName
enum:
- scheduleName
- dashboardName
- ownerName
- lastRun
- lastRunStatus
description: The field to sort results by.
- name: sortDirection
in: query
schema:
type: string
default: desc
enum:
- asc
- desc
description: The direction to sort results.
- name: cursor
in: query
schema:
type: integer
default: 1
description: The page number for offset-based pagination.
- name: pageSize
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: The number of results to include on each page.
- name: ownerId
in: query
schema:
type: string
format: uuid
description: 'Filter schedules by the owner''s membership ID. Use the [List users](/api/users/list-users) endpoint to retrieve membership IDs.
API results vary by API key type:
- **Organization API keys** - When specified, only schedules for the specified owner are returned. Otherwise, all schedules in the organization are returned.
- **Personal access token** - When specified, only the token owner''s membership ID is allowed. If another user''s membership ID is provided, the API will return a `403 Forbidden` error.
'
- name: embedEntity
in: query
schema:
type: string
description: 'Filter schedules by embed entity:
- If used as the only filter, list all schedules in the embed entity
- If used with `ownerId`, list only schedules for the specified user if they are associated with the `embedEntity`. The response will be empty if the specified `ownerId` doesn''t have the entity.
- Can be combined with other filters for more specific results
'
- name: identifier
in: query
schema:
type: string
description: 'Filter schedules by dashboard ID. 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`
'
responses:
'200':
description: Paginated schedule list
content:
application/json:
schema:
type: object
properties:
pageInfo:
$ref: '#/components/schemas/PageInfo'
records:
type: array
description: List of schedule records.
items:
type: object
properties:
id:
type: string
format: uuid
description: The schedule ID.
schedule:
type: string
description: The cron expression for the schedule.
disabledAt:
type: string
format: date-time
nullable: true
description: Timestamp when the schedule was paused, if applicable.
name:
type: string
description: The name of the schedule.
timezone:
type: string
description: The IANA timezone for the schedule.
identifier:
type: string
description: The ID of the dashboard associated with the schedule.
dashboardName:
type: string
description: The name of the dashboard associated with the schedule.
ownerId:
type: string
format: uuid
description: The membership ID of the schedule owner. Use the [List users](/api/users/list-users) endpoint to retrieve membership IDs.
ownerName:
type: string
description: The name of the schedule owner.
lastCompletedAt:
type: string
format: date-time
nullable: true
description: Timestamp of the last completed run.
lastStatus:
type: string
nullable: true
description: Status of the last run (e.g., `COMPLETE`, `ERROR_DELIVERED`).
destinationType:
type: string
description: The destination type (e.g., `email`, `webhook`, `sftp`, `slack`).
format:
type: string
description: The output format of the schedule. (e.g., `CSV`, `JSON`)
recipientCount:
type: integer
description: Number of recipients. Returns `-1` for webhook destinations.
content:
type: string
description: Content type (`dashboard` or `single tile`).
slackRecipientType:
type: string
nullable: true
description: Slack recipient type, if applicable.
systemDisabledAt:
type: string
format: date-time
nullable: true
description: Timestamp when the schedule was system-disabled, if applicable.
systemDisabledReason:
type: string
nullable: true
description: Reason for system disabling, if applicable.
alert:
type: string
nullable: true
description: Alert configuration, if applicable.
'400':
description: 'Bad Request
Possible error messages:
- `Invalid enum value`
- `ownerId: Invalid uuid`
- `Page size cannot exceed 100`
- `Invalid page number. The last valid page is <number>.`
'
content:
application/json:
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/omni/refs/heads/main/openapi/omni-schedules-api-openapi.yml