curl --request PUT \
  --url https://{instance}.omniapp.co/api/v1/schedules/{scheduleId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Weekly Sales Report",
  "schedule": "0 9 * * 1",
  "timezone": "America/New_York",
  "format": "pdf",
  "destinationType": "email",
  "recipients": [
    "user1@example.com"
  ],
  "subject": "Weekly Sales Report"
}
'

{
  "scheduledTaskId": "123e4567-e89b-12d3-a456-426614174000",
  "success": true
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

Schedule APIs

Update schedule

Update the specified task, whether it delivers a dashboard or a tab of a workbook. Changes to the schedule are applied to future runs. Currently running jobs are not affected.

A schedule’s entity (dashboard or workbook) is set when the schedule is created and can’t change. If the request body includes an entity value, it has no effect.

This endpoint replaces the schedule’s entire configuration — it is not a partial update. The request must include every required field for the destination type. Any optional property left out of the request is reset to its default, not left at its current value. This includes filterConfig (filter values are cleared), fanOut (treated as false, unless your organization’s delivery personalization setting is set to Always), conditionType and conditionQueryMapKey (the alert condition is removed), queryIdentifierMapKey, containerPages (selected pages are cleared), maxRowLimit, textBody, filename, and the paper and layout options.

The one exception is timezoneOverride: it keeps its current value when omitted, but only if query timezone overrides are enabled for the connection or document. Otherwise, it’s cleared.

To change a single property, send the schedule’s full configuration with that property changed.

PUT

schedules

{scheduleId}

curl --request PUT \
  --url https://{instance}.omniapp.co/api/v1/schedules/{scheduleId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Weekly Sales Report",
  "schedule": "0 9 * * 1",
  "timezone": "America/New_York",
  "format": "pdf",
  "destinationType": "email",
  "recipients": [
    "user1@example.com"
  ],
  "subject": "Weekly Sales Report"
}
'

{
  "scheduledTaskId": "123e4567-e89b-12d3-a456-426614174000",
  "success": true
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

Authorizations

Authorization

string

header

required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Path Parameters

scheduleId

string<uuid>

required

The ID of the schedule. To find a schedule's ID:

Navigate to the dashboard or workbook.
Click File > Deliveries & Alerts.
Next to a schedule, click Edit.

The schedule's ID is in the page's URL, after /schedules/. For example, the schedule ID in this URL is 123e4567-e89b-12d3-a456-426614174000:

https://blobsrus.omniapp.co/dashboards/e23ebaa0/schedules/123e4567-e89b-12d3-a456-426614174000

Body

application/json

Email
Webhook
SFTP
Slack
S3

name

string

required

The name of the scheduled task. Must be at least 1 character.

Minimum string length: 1

Example:

"Weekly Sales Report"

schedule

string

required

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.

Example:

"0 9 ? * MON *"

timezone

string

required

The IANA timezone for interpreting the schedule. Must be a valid IANA timezone identifier.

Example:

"America/New_York"

format

enum<string>

required

The output format of the task.

Available options:

link_only,

pdf,

png,

csv,

xlsx,

json

Example:

"pdf"

destinationType

enum<string>

required

The destination type for delivering to email recipients.

Available options:

email

Example:

"email"

recipients

required

Email recipients. Can be email addresses or user group IDs (if allowed).

Minimum string length: 1

subject

string

required

The subject line of the email. Must be at least 1 character.

Minimum string length: 1

Example:

"Weekly Sales Report"

timezoneOverride

string | null

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). Omitting it keeps the current value only while query timezone overrides are enabled for the connection or document; otherwise it is cleared.

Example:

"Europe/Paris"

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 document. For a workbook delivery, this must be a tab of the published workbook.

In responses, null for standard schedules.

Example:

"Jmn2r3KV"

conditionType

enum<string>

Required if conditionQueryMapKey is provided. Defines the type of condition to use for alerts.

Available options:

RESULTS_CHANGED,

RESULTS_UNCHANGED,

RESULTS_PRESENT,

RESULTS_MISSING

Example:

"RESULTS_PRESENT"

enableConditionalFormatting

boolean

default:true

Compatible with xlsx format only. When true, conditional formatting rules from the visualization are included in the Excel output.

Example:

true

enableFormatting

boolean

default:false

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.

Example:

false

expandTablesToShowAllRows

boolean

default:false

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.

Example:

false

expandAiSummaries

boolean

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.

Example:

false

filterConfig

object

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.

Example:

{ "status": ["active", "pending"] }

hideHiddenFields

boolean

default:false

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

Example:

false

hideTitle

boolean

default:false

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

Example:

false

killJobsOnFailure

boolean

default:false

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

Example:

false

maxRowLimit

number

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

Required range: x >= 1

Example:

1000

overrideRowLimit

boolean

default:false

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.

Example:

false

paperFormat

enum<string>

Compatible with pdf format. Defines the paper format (size) of the resulting PDF.

Available options:

a3,

a4,

fit_page,

legal,

letter,

tabloid

Example:

"letter"

paperOrientation

enum<string>

Compatible with pdf format. Defines the paper orientation of the resulting PDF.

Available options:

portrait,

landscape

Example:

"landscape"

queryIdentifierMapKey

string

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: json with enableFormatting: true
format: xlsx with overrideRowLimit: true
entity: workbook

Example:

"Jmn2r3KV"

containerPages

string[]

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:

pdf renders the listed pages in storage order.
png accepts exactly one page.
csv and xlsx keep 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.

Minimum array length: 1

Example:

["01KXH5TG58BB5JBJHGTPC62RZA"]

rebuildExtracts

boolean

default:false

If true, rebuild extracts before running the schedule. Cannot be combined with useCache.

Example:

false

showContentLink

boolean

default:true

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

Example:

true

showFilters

boolean

default:true

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

Example:

true

singleColumnLayout

boolean

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

Example:

false

useCache

boolean

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

Example:

false

fanOut

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

filename

string

Optional custom filename for the attachment (without extension). Must not contain special characters.

Example:

"weekly-sales-report"

textBody

string

Optional plain text body content for the email.

Example:

"Please find attached the weekly sales report."

Response

Schedule updated successfully

scheduledTaskId

string<uuid>

required

The UUID of the updated scheduled task.

Example:

"123e4567-e89b-12d3-a456-426614174000"

success

boolean

required

Whether the operation was successful.

Example:

true

Getting started

Who am I?

Administration APIs

AI APIs

App APIs

Branch APIs

Connection APIs

Content APIs

Dashboard APIs

Document APIs

Embed APIs

Folder APIs

Label APIs

Model APIs

Query APIs

Schedule APIs

Upload APIs

User APIs

User group APIs

Update schedule

Authorizations

Path Parameters

Body

Response