Create schedule
Create a scheduled task delivering a document’s dashboard, or one tab of its workbook with entity: workbook. Supports applying filters and formatting, creating alert conditions, and triggering test deliveries.
Supports the following destinations:
Authorizations
Can be either an Organization API Key or Personal Access Token (PAT).
Include in the Authorization header as: Bearer YOUR_TOKEN
Query Parameters
Only supported when using an Organization API key. The membership ID of the user who should own the schedule. The specified user must have permission to view and schedule the document, not just view it. 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
userIdis provided, the schedule is owned by the specified user - If
userIdis 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.
Body
- Email
- Webhook
- SFTP
- Slack
- S3
The name of the scheduled task. Must be at least 1 character.
1"Weekly Sales Report"
When the task runs, as an AWS EventBridge cron expression: minute hour day-of-month month day-of-week year. Runs cannot be more frequent than once an hour unless the organization allows a higher frequency. Delivery times are approximate and happen within 15 minutes of the scheduled time.
"0 9 ? * MON *"
The IANA timezone for interpreting the schedule. Must be a valid IANA timezone identifier.
"America/New_York"
The ID of the document where the task will be created. This identifier is shared by the document's dashboard and workbook. This can be retrieved by:
- Opening the document settings - Navigate to File > Settings... in the dashboard. The Identifier field contains the document's ID.
- Using the dashboard's URL - The string after
/dashboardsis the document's ID; for example:https://myorg.omniapp.co/dashboards/12db1a0a
The output format of the task.
link_only, pdf, png, csv, xlsx, json "pdf"
The destination type for delivering to email recipients.
email "email"
Email recipients. Can be email addresses or user group IDs (if allowed).
1The subject line of the email. Must be at least 1 character.
1"Weekly Sales Report"
Optional IANA timezone applied to query execution at render time. Distinct from timezone (which controls when the schedule fires). Pass null to clear it (use the default).
"Europe/Paris"
What to deliver: the document's dashboard, or a tab of its workbook. Defaults to dashboard.
With entity: workbook, queryIdentifierMapKey is required to name the tab, and filterConfig and singleColumnLayout aren't supported.
dashboard, workbook Required if conditionType is provided. The ID of the query to monitor for triggering an alert. Must reference a valid query in the document. For a workbook delivery, this must be a tab of the published workbook.
In responses, null for standard schedules.
"Jmn2r3KV"
Required if conditionQueryMapKey is provided. Defines the type of condition to use for alerts.
RESULTS_CHANGED, RESULTS_UNCHANGED, RESULTS_PRESENT, RESULTS_MISSING "RESULTS_PRESENT"
Dashboard deliveries only. Compatible with pdf, png, csv, and xlsx formats, on dashboards using the advanced (multi-page) layout. The instanceKeys of the pages to render:
pdfrenders the listed pages in storage order.pngaccepts exactly one page.csvandxlsxkeep only the tiles on the selected pages.
Cannot be combined with queryIdentifierMapKey. Defaults to the dashboard's first page for pdf and png, and to every tile for csv and xlsx.
1Compatible with xlsx format only. When true, conditional formatting rules from the visualization are included in the Excel output.
true
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.
false
Compatible with pdf and png formats. If true, AI summary tiles grow to show their full text, splitting across pages when paperFormat isn't fit_page.
With paperFormat: fit_page, the page grows instead, and the operation fails if the page would be taller than 60,000px.
false
Compatible with pdf and png formats. If true, up to 1,000 rows in table visualizations will be included in the delivery.
With paperFormat: fit_page, the page grows to fit the rows, and the delivery fails if the page would be taller than 60,000px.
false
Dashboard deliveries only. An object specifying the filter conditions to apply to the task. The filter key specified must already exist in the dashboard.
Use the Get dashboard filters and controls endpoint to retrieve filter configuration objects.
Note: Filter keys are case-sensitive and must match exactly.
Compatible with csv and xlsx formats. If true, fields marked as hidden won't be displayed in the task's output.
false
Compatible with pdf and png formats. If true, the content's title will be hidden in the task's output.
false
If true, stops the entire job if any queries included in the task fail.
false
Compatible with csv, json, and xlsx formats. Used with overrideRowLimit. Specifies the maximum number of rows.
x >= 11000
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.
false
Compatible with pdf format. Defines the paper format (size) of the resulting PDF.
a3, a4, fit_page, legal, letter, tabloid "letter"
Compatible with pdf format. Defines the paper orientation of the resulting PDF.
portrait, landscape "landscape"
Required for single tile tasks and for workbook deliveries (entity: workbook). The ID of the query to include in a single tile task, or the ID of the workbook tab to deliver. Must reference a valid query in the document.
Required for:
format: jsonwithenableFormatting: trueformat: xlsxwithoverrideRowLimit: trueentity: workbook
"Jmn2r3KV"
If true, rebuild extracts before running the schedule. Cannot be combined with useCache.
false
Compatible with all formats except link_only. If true, a link to the content will be shown in the task's output.
true
Compatible with all formats except link_only and csv. If true, filters will be shown in the task's output.
true
Dashboard deliveries only. Compatible with pdf and png formats. If true, dashboard tiles will be arranged into a single vertical column.
false
If true, run the task immediately instead of scheduling. Not supported for RESULTS_CHANGED and RESULTS_UNCHANGED alert conditions, or for s3 destinations: create the schedule first, then use the trigger endpoint.
false
If true, allow scheduled queries to use cached results instead of always running fresh queries. An alert always runs its condition check fresh. Only the delivery sent once the condition is met uses cached results. Cannot be combined with rebuildExtracts.
false
Applicable to email destinations. If true, send individual emails to each recipient.
If your organization's delivery personalization setting is set to Never, fanOut is always persisted as false regardless of the submitted value. If set to Always, personalization is forced on for all deliveries. See Personalizing email deliveries for more information.
Note: Personalized deliveries aren't supported for connections that use OAuth sign-in. In this case, the delivery will fail.
Optional custom filename for the attachment (without extension). Must not contain special characters.
"weekly-sales-report"
Optional plain text body content for the email.
"Please find attached the weekly sales report."
Response
Schedule created successfully
The ID of the created schedule.
A success message.
"Successfully created schedule"
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.
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.