Schedule APIs

The schedule APIs allow you to manage and interact with schedules within your Omni organization.

Create a schedule

Creates a scheduled task for the specified dashboard.

Supports applying filters and formatting, creating alert conditions, and triggering test deliveries.

Limitations

Currently, only email, SFTP, and webhook destinations are supported.

POST /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "identifier": "12db1a0a",
    "name": "My Webhook schedule",
    "schedule": "0 9 ? * * *",
    "timezone": "UTC",
    "format": "json",
    "destinationType": "webhook",
    "url": "https://webhooksrus.com/1234566"
}'

POST /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "identifier": "12db1a0a",
    "name": "My Email schedule",
    "schedule": "0 9 ? * * *",
    "timezone": "UTC",
    "format": "pdf",
    "destinationType": "email",
    "paperFormat": "legal",
    "expandTablesToShowAllRows": true,
    "paperOrientation": "landscape",
    "recipients": [
        "iamagoodblob@myorg.co",
        "blobmanager@myorg.co"
    ],
    "subject": "Daily Sales report",
    "textBody": "Here are the daily sales!",
    "fanOut": "false"
}'

POST /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "identifier": "12db1a0a",
    "name": "My SFTP schedule",
    "schedule": "0 9 ? * * *",
    "timezone": "UTC",
    "format": "xlsx",
    "destinationType": "sftp",
    "address": "sftp.blobsrus.com",
    "port": "22",
    "username": "blobby",
    "passwordUnencrypted": "1am@g00dBL0b"
}'

Filters - Use filterConfig to specify filter conditions. Filter keys must exist in the dashboard filter configuration to be valid. If the dashboard doesn't have any filter keys configured, filters can't be used in the task.

Filter keys are case-sensitive and must match exactly.
Formatting options - You can also specify options to format the task's output, such as hideTitle. Note: Not all output formats (json, email, etc.) are compatible with each formatting option. Refer to the Parameters table for more information.

POST /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "identifier": "dashboard-abc123",
    "name": "Weekly Regional Report",
    "schedule": "0 0 ? * MON *",
    "timezone": "UTC",
    "format": "pdf",
    "destinationType": "email",
    "recipients": ["iamagoodblob@myorg.com", "managerblob@emyorg.com"],
    "subject": "Weekly Regional Report",
    "filterConfig": {
      "region": {
        "kind": "EQ",
        "left_side": "US",
        "type": "string"
      }
    },
    "hideTitle": true
  }'

To specify an alert condition, provide:

conditionType
conditionQueryMapKey

POST /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "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
  }'

To scope the delivery to a single tile, provide a queryIdentifierMapKey.

POST /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "identifier": "dashboard-abc123",
    "name": "Single tile delivery",
    "schedule": "0 */6 * * ? *",
    "timezone": "UTC",
    "format": "json",
    "destinationType": "webhook",
    "url": "https://api.example.com/webhook",
    "queryIdentifierMapKey": "1",
    "overrideRowLimit": true,
    "maxRowLimit": 1000
  }'

POST /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authentication: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "identifier": "dashboard-abc123",
    "name": "Test Delivery",
    "schedule": "0 0 1 1 ? 2099",
    "timezone": "UTC",
    "format": "pdf",
    "destinationType": "email",
    "recipients": ["iamagoodblob@myorg.com"],
    "subject": "Test Delivery",
    "testNow": true
  }'

Parameters

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

200 OK
{
  "id": "2abba91d-9bec-41a0-8a8d-6f133b4ff0b7",
  "message": "Successfully created schedule"
}

400 Bad Request

Response bodies will be an object similar to the following:

{
    "detail": "<errorReason>",
    "status": 400
}

Issue	Error detail
Document has not been saved	`Analyses do not support dashboards.`
Document is missing a dashboard	`Document does not have a dashboard`
Invalid cron expression	`schedule: Schedule is an invalid cron expression`
Invalid `timezone`	`timezone: Time zone must be IANA valid.`
`hideTitle` used with incompatbile `format`	`hideTitle can only be used with PDF or PNG formats`
Invalid filter key	`Invalid filter keys found in schedule configuration: <filterKey>. Available dashboard filter keys are: <key1>, <key2>, ....`
`testNow` used with incompatible `conditionType`	`Test delivery not supported for condition type RESULTS_CHANGED`
Format incompatible with print options	`Print options are not supported for this format`
`paperFormat: fit_page` incompatible with layout options	`Single column layout and table expansion options are not supported for FIT_PAGE format.`
Alert conditions require a condition type and trigger query	`Must provide both a trigger query and an alert condition type`

404 Not Found

Response bodies will be an object similar to the following:

{
    "detail": "<errorReason>",
    "status": 404
}

Issue	Error detail
Dashboard not found	`Document with identifier \"<dashboardId>\" not found`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Edit a schedule

Updates the specified task.

Changes to the schedule will be applied to future runs. Currently running jobs are not affected.

PUT /api/v1/schedules/:scheduleId
curl -L -X 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "name": "Weekly Sales Report",
    "schedule": "0 9 * * MON",
    "timezone": "America/New_York",
    "format": "pdf",
    "destinationType": "email",
    "recipients": ["team@company.com"],
    "subject": "Weekly Sales Dashboard",
    "paperFormat": "letter",
    "paperOrientation": "landscape"
  }'

Parameters

info

Only properties included in the request will be updated. Omitted properties will retain their current values.

Note: The scheduleId must be provided as a path parameter.

Loading parameters...

Responses

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

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

400 Bad Request

Response bodies will be an object similar to the following:

{
    "detail": "<errorReason>",
    "status": 400
}

Issue	Error detail
Invalid UUID format	`Bad Request: scheduleId: Invalid uuid`
Invalid method	`Invalid method`
Missing required parameters	`Bad Request: name: name is required, schedule: schedule is required, timezone: timezone is required, destinationType: Invalid discriminator value. Expected email \| webhook \| sftp`
Invalid cron expression	`schedule: Schedule is an invalid cron expression`
Invalid `timezone`	`timezone: Time zone must be IANA valid.`
`hideTitle` used with incompatbile `format`	`hideTitle can only be used with PDF or PNG formats`
Invalid filter key	`Invalid filter keys found in schedule configuration: <filterKey>. Available dashboard filter keys are: <key1>, <key2>, ....`
Format incompatible with print options	`Print options are not supported for this format`
`paperFormat: fit_page` incompatible with layout options	`Single column layout and table expansion options are not supported for FIT_PAGE format.`

404 Not Found

{
  "detail": "<errorReason>",
  "status": 404
}

Error	Error detail
Schedule not found	`Scheduled task with id {scheduleId} does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

List schedules

Retrieves scheduled tasks. This endpoint supports filtering, sorting, and cursor-based pagination.

To retrieve the recipients for a schedule, use the List schedule recipients endpoint.

Basic request
Filters
Sorting
Pagination with cursor

GET /api/v1/schedules
curl -L 'https://myorg.omniapp.co/api/v1/schedules' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

Full text search (q=<value>):

GET /api/v1/schedules?q=<value>
curl -L 'https://myorg.omniapp.co/api/v1/schedules?q=Blob%20Ross' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

Filter fields (ex: status, destination):

GET /api/v1/schedules?<filterField>=<value>
curl -L 'https://myorg.omniapp.co/api/v1/schedules?status=success&destination=email' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

Full text & filter fields:

GET /api/v1/schedules?q=<value>&=<value>
curl -L 'https://myorg.omniapp.co/api/v1/schedules?q=Blob%20Ross&status=success&destination=email' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

GET /api/v1/schedules?sortField=<field>&sortDirection=<direction>
curl -L 'https://myorg.omniapp.co/api/v1/schedules?sortField=lastRun&sortDirection=desc' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

GET /api/v1/schedules?cursor=<pageNumber>&pageSize=<size>
curl -L 'https://myorg.omniapp.co/api/v1/schedules?cursor=2&pageSize=10' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

Parameters

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "pageInfo": {
    "hasNextPage": false,
    "nextCursor": null,
    "pageSize": 20,
    "totalRecords": 6
  },
  "records": [
    {
      "id": "60d386ca-6f48-4143-9bfc-fd7a6f942c2c",
      "schedule": "00 09 ? * 2,3,4,5,6 *",
      "disabledAt": "2024-03-01T15:32:20.996Z",
      "name": "Web Traffic Analysis",
      "timezone": "America/Los_Angeles",
      "identifier": "1169b547",
      "dashboardName": "Web Traffic Analysis",
      "ownerName": "Blob Ross",
      "lastCompletedAt": "2024-02-29T17:00:56.107Z",
      "lastStatus": "COMPLETE",
      "destinationType": "email",
      "recipientCount": 5,
      "content": "dashboard",
      "slackRecipientType": null,
      "systemDisabledAt": null,
      "systemDisabledReason": null,
      "alert": null
    },
    {
      "id": "f68aba72-b558-4012-a381-bb74954dd025",
      "schedule": "00 09 ? * 2,3,4,5,6 *",
      "disabledAt": null,
      "name": "⚡️🍣 Query",
      "timezone": "America/New_York",
      "identifier": "eadde573",
      "dashboardName": "Blob R Us Sales",
      "ownerName": "Blobby Hill",
      "lastCompletedAt": "2025-05-19T13:00:35.457Z",
      "lastStatus": "ERROR_DELIVERED",
      "destinationType": "email",
      "recipientCount": 1,
      "content": "single tile",
      "slackRecipientType": null,
      "systemDisabledAt": null,
      "systemDisabledReason": null,
      "alert": null
    },
    {
      "id": "2af41989-1bed-4c65-a602-927f71205a32",
      "schedule": "00 09 ? * 2,3,4,5,6 *",
      "disabledAt": null,
      "name": "Orders (2)",
      "timezone": "America/New_York",
      "identifier": "12db1a0a",
      "dashboardName": "Orders",
      "ownerName": "Blobby Hill",
      "lastCompletedAt": "2025-05-19T13:00:27.517Z",
      "lastStatus": "COMPLETE",
      "destinationType": "webhook",
      "recipientCount": -1,
      "content": "dashboard",
      "slackRecipientType": null,
      "systemDisabledAt": null,
      "systemDisabledReason": null,
      "alert": null
    },
    {
      "id": "61a8e93b-71f4-4cda-b1f9-a91aa0ad05bc",
      "schedule": "00 09 ? * 2,3,4,5,6 *",
      "disabledAt": null,
      "name": "Orders",
      "timezone": "America/New_York",
      "identifier": "12db1a0a",
      "dashboardName": "Orders",
      "ownerName": "Blob Ross",
      "lastCompletedAt": "2025-05-19T13:00:25.376Z",
      "lastStatus": "COMPLETE",
      "destinationType": "email",
      "recipientCount": 1,
      "content": "dashboard",
      "slackRecipientType": null,
      "systemDisabledAt": null,
      "systemDisabledReason": null,
      "alert": null
    },
    {
      "id": "3db84f26-db0f-451d-846e-0f7148ae5a7d",
      "schedule": "00 09 ? * 2,3,4,5,6 *",
      "disabledAt": "2024-12-31T17:23:45.063Z",
      "name": "External users",
      "timezone": "America/New_York",
      "identifier": "0958c2d8",
      "dashboardName": "Sales Data by Quarter",
      "ownerName": "Blobby Hill",
      "lastCompletedAt": "2024-12-31T14:00:51.558Z",
      "lastStatus": "COMPLETE",
      "destinationType": "email",
      "recipientCount": 1,
      "content": "dashboard",
      "slackRecipientType": null,
      "systemDisabledAt": null,
      "systemDisabledReason": null,
      "alert": null
    },
    {
      "id": "8cc895ec-a2af-493f-a4e4-08c3017fa42d",
      "schedule": "00 09 ? * 2,3,4,5,6 *",
      "disabledAt": "2024-11-21T21:52:16.059Z",
      "name": "Daily Slack update",
      "timezone": "America/New_York",
      "identifier": "0958c2d8",
      "dashboardName": "Sales Data by Quarter",
      "ownerName": "Blobby Hill",
      "lastCompletedAt": null,
      "lastStatus": null,
      "destinationType": "slack",
      "recipientCount": 1,
      "content": "dashboard",
      "slackRecipientType": "users",
      "systemDisabledAt": null,
      "systemDisabledReason": null,
      "alert": null
    }
  ]
}

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Error	Error detail
Invalid parameter value	`Invalid enum value`
Invalid `ownerId` UUID	`ownerId: Invalid uuid`
Invalid page size	`Page size cannot exceed 100`
Invalid page number for `cursor`	`Invalid page number. The last valid page is <number>.`

404 Not Found

{
  "detail": "<errorReason>",
  "status": 404
}

Error	Error detail
User not found	`User with id <id> does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Trigger schedule

Triggers the execution of a schedule on demand, outside of its regular schedule.

POST /api/v1/schedules/:scheduleId/trigger

curl -L -X POST 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/trigger' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: The scheduleId must be provided as a path parameter.

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "success": true
}

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Error	Error detail
Invalid UUID format	`Bad Request: scheduleId: Invalid uuid`
Invalid method	`Invalid method`

404 Not Found

{
  "detail": "<errorReason>",
  "status": 404
}

Error	Error detail
Schedule not found	`Scheduled task with id {scheduleId} does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

500 Internal Server Error

{
  "detail": "<errorReason>",
  "status": 500
}

Error	Error detail
Dispatcher error	Various error messages related to dispatch failures

Transfer schedule ownership

Transfers ownership of a schedule from one user to another user in the same organization. New ownership will be immediate and can't be reversed using this endpoint.

How ownership transfer affects schedule execution depends on the type of destination the schedule uses, and for email destinations, whether the Personalize delivery with the recipient's user attributes is enabled:

	Slack, SFTP, & Webhooks	Email without personalization	Email with personalization
Future jobs are executed by...	New owner	New owner	Each recipient
Permissions, data access, & user attributes are based on...	New owner	New owner	Each recipient
Output is generated using...	New owner access	New owner access	Recipient access

PUT /api/v1/schedules/:scheduleId/transfer-ownership
curl -L -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/transfer-ownership' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "userId": "987fcdeb-51a2-43d7-9b56-254415f67890"
}'

Parameters

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "success": true
}

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Error	Error detail
User UUID is invalid or missing	`Bad Request: userId: Invalid user ID`
User already owns the schedule	`User is already the owner of this schedule`

403 Forbidden

{
  "detail": "<errorReason>",
  "status": 403
}

Error	Error detail
New owner has insufficient content permissions	`New owner cannot view dashboard`

404 Not Found

{
  "detail": "<errorReason>",
  "status": 404
}

Error	Error detail
Schedule not found	`Scheduled task with id {scheduleId} does not exist`
New owner not member of organization	`Membership with id {userId} does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Pause a schedule

Pauses a schedule using the schedule's UUID.

PUT /api/v1/schedules/:scheduleId/pause

curl -L -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/pause' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: The scheduleId must be provided as a path parameter.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "success": true
}

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Schedule is system disabled	`Schedule is system disabled`
Schedule is already paused	`Schedule is already paused`

404 Not Found

{
  "detail": "<errorReason>",
  "status": 404
}

Issue	Error detail
Schedule not found	`Scheduled task with id {scheduleId} does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Resume a schedule

Resumes a schedule using the schedule's UUID.

PUT /api/v1/schedules/:scheduleId/resume

curl -L -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/resume' \
-H 'Authorization: Bearer <TOKEN>'

Parameters

Note: The scheduleId must be provided as a path parameter.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "success": true
}

Field	Type	Description
success	boolean	Indicates schedule has been resumed successfully

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Issue	Error detail
Schedule is system disabled	`Schedule is system disabled`
Schedule is already resumed	`Schedule is already resumed`

404 Not Found

{
  "detail": "<errorReason>",
  "status": 404
}

Issue	Error detail
Schedule not found	`Scheduled task with id {scheduleId} does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Delete a schedule

Deletes a schedule using the schedule's UUID.

DELETE /api/v1/schedules/:scheduleId
curl -L -X DELETE 'https://myorg.omniapp.co/api/v1/schedules/61a8e93b-71f4-4cda-b1f9-a91aa0ad05bc' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json'

Parameters

Loading parameters...

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
    "success": true
}

400 Bad Request

{
  "detail": "<errorReason>",
  "status": 400
}

Error	Error detail
Invalid schedule UUID	`scheduleId: Invalid uuid`
Invalid method	`Invalid request method`

404 Not Found

{
  "detail": "<errorReason>",
  "status": 404
}

Error	Error detail
Schedule not found	`Scheduled task with id <scheduleId> does not exist`

429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

Create a schedule​

Limitations​

Parameters​

Response​

Edit a schedule​

Parameters​

Responses​

List schedules​

Parameters​

Response​

Trigger schedule​

Parameters​

Response​

Transfer schedule ownership​

Parameters​

Response​

Pause a schedule​

Parameters​

Response​

Resume a schedule​

Parameters​

Response​

Delete a schedule​

Parameters​

Response​

Create a schedule

Limitations

Parameters

Response

Edit a schedule

Parameters

Responses

List schedules

Parameters

Response

Trigger schedule

Parameters

Response

Transfer schedule ownership

Parameters

Response

Pause a schedule

Parameters

Response

Resume a schedule

Parameters

Response

Delete a schedule

Parameters

Response