Sign in

v1

latestOpenAPI 3.1.02026-07-2618690613.4 KB
Schedules

Create schedule

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
  • Slack - Note: A Slack workspace must already be connected to Omni to use this destination type.
  • SFTP
  • Webhook
  • Amazon S3
post/v1/schedules

Query parameters

userIdstring uuid

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

Request body

identifierstring 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
namestring required

The name of the task.

schedulestring required

A cron expression defining when the schedule will run, in Amazon Web Services (AWS) Cloudwatch syntax.

Note: Delivery times are approximate and will happen within 15 minutes of the specified schedule run time.

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

filterConfigobject

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

conditionQueryMapKeystring

Required if conditionType is provided. The ID of the query to monitor for triggering an alert. Must reference a valid query in the dashboard.

queryIdentifierMapKeystring

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
killJobsOnFailureboolean

If true, stop the entire job if any queries included in the task fail.

testNowboolean

If true, run the task immediately instead of scheduling.

Not supported for RESULTS_CHANGED alert conditions or s3 destinations.

hideTitleboolean

Compatible with pdf and png formats. If true, the content's title will be hidden in the task's output.

hideHiddenFieldsboolean

Compatible with csv and xlsx formats. If true, fields marked as hidden won't be displayed in the task's output.

enableFormattingboolean

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.

overrideRowLimitboolean

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.

maxRowLimitinteger

Compatible with csv, json, and xlsx formats. Used with overrideRowLimit. Specifies the maximum number of rows.

showContentLinkboolean

Compatible with all formats except link_only. If true, a link to the content will be shown in the task's output.

showFiltersboolean

Compatible with all formats except link_only and csv. If true, filters will be shown in the task's output.

expandTablesToShowAllRowsboolean

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.

singleColumnLayoutboolean

Compatible with pdf and png formats. If true, dashboard tiles will be arranged into a single vertical column.

urlstring

Required if destinationType: webhook. A webhook URL. Must be a valid HTTP/HTTPS URL.

subjectstring

Required if destinationType: email. Email subject line.

textBodystring

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
fanOutboolean

Applicable to email destinations. If true, send individual emails to each recipient.

addressstring

Required if destinationType: sftp. SFTP server address.

portinteger

Required if destinationType: sftp. SFTP port.

usernamestring

Required if destinationType: sftp. SFTP username.

pathstring

Required if destinationType: sftp. Remote file path.

passwordUnencryptedstring

Applicable to SFTP destinations. SFTP password.

bucketNamestring

Required if destinationType: s3. The name of the target S3 bucket. Must be 3-63 characters, lowercase letters, numbers, hyphens, and periods only.

regionstring

Required if destinationType: s3. The AWS region of the S3 bucket (e.g., us-east-1).

roleArnstring

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.

keyPrefixstring

Applicable to S3 destinations. Folder path prefix for the uploaded file (e.g., reports/daily/). Must not contain path traversal sequences.

filenamestring

Applicable to S3 destinations. Filename template (without extension) using Mustache syntax. Supported variables: {{currentDate}}, {{currentTime}}, {{currentYear}}, {{currentMonth}}, {{currentDay}}, {{yesterdayDate}}, {{timeZone}}, {{entityName}}, {{format}}, {{scheduledTaskName}}.

Example request

{
  "bucketName": "my-reports-bucket",
  "region": "us-east-1",
  "roleArn": "arn:aws:iam::123456789012:role/OmniS3DeliveryRole",
  "keyPrefix": "reports/daily/",
  "filename": "{{scheduledTaskName}}_{{currentDate}}"
}

Response

Schedule created successfully

idstring uuid

The ID of the created schedule.

messagestring

A success message.

delivererRoleArnstring

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.

externalIdstring

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.

Example response

{
  "message": "Successfully created schedule"
}