Schedule APIs

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

List schedules

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

Basic request
Filters
Sorting
Pagination with cursor

GET /api/v1/schedules
curl -X GET '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 -X GET '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 -X GET '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 -X GET '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 -X GET '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 -X GET '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.

Basic request

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

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

Add recipients to schedule

Adds one or more recipients to an existing scheduled email task. Recipients can be specified by email address or user ID.

Limitations

This API only works with schedules with email destinations.

Add by email
Add by user ID
Add multiple recipients

PUT /api/v1/schedules/:scheduleId/add-recipients
curl -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/add-recipients' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json' \
--d '{
  "emails": ["user@example.com"]
}'

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

PUT /api/v1/schedules/:scheduleId/add-recipients
curl -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/add-recipients' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json' \
--d '{
  "emails": ["user1@example.com", "user2@example.com"],
  "userIds": ["987fcdeb-51a2-43d7-9b56-254415f67890", "abcdef12-3456-7890-abcd-ef1234567890"]
}'

Parameters

Loading parameters...

Response

200 OK

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

{
  "addedRecipientsCount": 2,
  "success": true
}

400 Bad Request

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

Error	Error detail
Invalid UUID format	`userIds: Invalid uuid`
Invalid email format	`emails: Invalid email address`
Empty request body	`Please provide either valid email addresses, valid user IDs, or both`
No recipients provided	- `At least one recipient must be provided` - `{parameter}: Array must contain at least 1 element(s)`
Invalid members	`Invalid recipient(s): The following members do not exist or do not have access to this organization: {userId}`
Unsupported destination type	`Cannot add recipients to destination type {destinationType}`

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.

Remove recipients from schedule

Removes one or more recipients from an existing scheduled email task. Recipients can be specified by email address or user ID.

Limitations

This API only works with schedules with email destinations.

Remove by email
Remove by user ID
Remove multiple recipients

PUT /api/v1/schedules/:scheduleId/remove-recipients
curl -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/remove-recipients' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json' \
--d '{
  "emails": ["user@example.com"]
}'

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

PUT /api/v1/schedules/:scheduleId/remove-recipients
curl -X PUT 'https://myorg.omniapp.co/api/v1/schedules/123e4567-e89b-12d3-a456-426614174000/remove-recipients' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json' \
--d '{
  "emails": ["user1@example.com", "user2@example.com"],
  "userIds": ["987fcdeb-51a2-43d7-9b56-254415f67890", "abcdef12-3456-7890-abcd-ef1234567890"]
}'

Parameters

Loading parameters...

Response

200 OK

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

{
  "removedRecipientsCount": 2,
  "success": true
}

400 Bad Request

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

Error	Error detail
Invalid UUID format	`Bad Request: userIds: Invalid uuid`
Invalid email format	`Bad Request: emails: Invalid email address`
Empty request body	`Please provide either valid email addresses, valid user IDs, or both`
No recipients provided	- `At least one recipient must be provided` - `{parameter}: Array must contain at least 1 element(s)`
Invalid members	`Invalid recipient(s): The following members do not exist or do not have access to this organization: {userId}`
Unsupported destination type	`Cannot change recipients on a scheduled task destination of type {destinationType}`

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.

Pause a schedule

Basic request

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

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

Basic request

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

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

List schedules​

Parameters​

Response​

Trigger schedule​

Parameters​

Response​

Add recipients to schedule​

Limitations​

Parameters​

Response​

Remove recipients from schedule​

Limitations​

Parameters​

Response​

Pause a schedule​

Parameters​

Response​

Resume a schedule​

Parameters​

Response​

Delete a schedule​

Parameters​

Response​

List schedules

Parameters

Response

Trigger schedule

Parameters

Response

Add recipients to schedule

Limitations

Parameters

Response

Remove recipients from schedule

Limitations

Parameters

Response

Pause a schedule

Parameters

Response

Resume a schedule

Parameters

Response

Delete a schedule

Parameters

Response