> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/api/schedules/list-schedules",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# 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](/api/schedule-recipients/list-schedule-recipients) endpoint.
## OpenAPI
````yaml /api/openapi.yaml get /v1/schedules
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: AI
description: AI-powered query generation
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Documents
description: Create, retrieve, and manage documents
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/schedules:
get:
tags:
- Schedules
summary: List schedules
description: >
Retrieves scheduled tasks. This endpoint supports filtering, sorting,
and cursor-based pagination.
To retrieve the recipients for a schedule, use the [List schedule
recipients](/api/schedule-recipients/list-schedule-recipients) endpoint.
operationId: listSchedules
parameters:
- name: q
in: query
schema:
type: string
description: >
Search term for filtering schedules by name, dashboard name, or
owner name (case-insensitive).
- name: status
in: query
schema:
type: string
enum:
- success
- error
- canceled
- none
description: Filter schedules by delivery status.
- name: destination
in: query
schema:
type: string
enum:
- email
- slack
- webhook
- sftp
- s3
description: Filter schedules by destination type.
- name: scheduleType
in: query
schema:
type: string
enum:
- alert
- schedule
description: Filter by schedule type.
- name: contentType
in: query
schema:
type: string
enum:
- dashboard
- single tile
description: Filter schedules by content type.
- name: sortField
in: query
schema:
type: string
default: scheduleName
enum:
- scheduleName
- dashboardName
- ownerName
- lastRun
- lastRunStatus
description: The field to sort results by.
- name: sortDirection
in: query
schema:
type: string
enum:
- asc
- desc
default: desc
description: The direction to sort results.
- name: cursor
in: query
schema:
type: integer
default: 1
description: The page number for offset-based pagination.
- name: pageSize
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: The number of results to include on each page.
- name: ownerId
in: query
schema:
type: string
format: uuid
description: >
Filter schedules by the owner's membership ID. Use the [List
users](/api/users/list-users) endpoint to retrieve membership IDs.
API results vary by API key type:
- **Organization API keys** - When specified, only schedules for the
specified owner are returned. Otherwise, all schedules in the
organization are returned.
- **Personal access token** - When specified, only the token owner's
membership ID is allowed. If another user's membership ID is
provided, the API will return a `403 Forbidden` error.
- name: embedEntity
in: query
schema:
type: string
description: >
Filter schedules by embed entity:
- If used as the only filter, list all schedules in the embed entity
- If used with `ownerId`, list only schedules for the specified user
if they are associated with the `embedEntity`. The response will be
empty if the specified `ownerId` doesn't have the entity.
- Can be combined with other filters for more specific results
- name: identifier
in: query
schema:
type: string
description: >
Filter schedules by dashboard ID. 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`
responses:
'200':
description: Paginated schedule list
content:
application/json:
schema:
type: object
properties:
pageInfo:
$ref: '#/components/schemas/PageInfo'
records:
type: array
description: List of schedule records.
items:
type: object
properties:
id:
type: string
format: uuid
description: The schedule ID.
schedule:
type: string
description: The cron expression for the schedule.
disabledAt:
type: string
format: date-time
nullable: true
description: >-
Timestamp when the schedule was paused, if
applicable.
name:
type: string
description: The name of the schedule.
timezone:
type: string
description: The IANA timezone for the schedule.
identifier:
type: string
description: >-
The ID of the dashboard associated with the
schedule.
dashboardName:
type: string
description: >-
The name of the dashboard associated with the
schedule.
ownerId:
type: string
format: uuid
description: >-
The membership ID of the schedule owner. Use the
[List users](/api/users/list-users) endpoint to
retrieve membership IDs.
ownerName:
type: string
description: The name of the schedule owner.
lastCompletedAt:
type: string
format: date-time
nullable: true
description: Timestamp of the last completed run.
lastStatus:
type: string
nullable: true
description: >-
Status of the last run (e.g., `COMPLETE`,
`ERROR_DELIVERED`).
destinationType:
type: string
description: >-
The destination type (e.g., `email`, `webhook`,
`sftp`, `slack`).
format:
type: string
description: >-
The output format of the schedule. (e.g., `CSV`,
`JSON`)
recipientCount:
type: integer
description: >-
Number of recipients. Returns `-1` for webhook
destinations.
content:
type: string
description: Content type (`dashboard` or `single tile`).
slackRecipientType:
type: string
nullable: true
description: Slack recipient type, if applicable.
systemDisabledAt:
type: string
format: date-time
nullable: true
description: >-
Timestamp when the schedule was system-disabled, if
applicable.
systemDisabledReason:
type: string
nullable: true
description: Reason for system disabling, if applicable.
alert:
type: string
nullable: true
description: Alert configuration, if applicable.
'400':
description: |
Bad Request
Possible error messages:
- `Invalid enum value`
- `ownerId: Invalid uuid`
- `Page size cannot exceed 100`
- `Invalid page number. The last valid page is .`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: |
Forbidden
Possible error messages:
- `Personal access tokens can only filter by their own ownerId`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: |
Not Found
Possible error messages:
- `User with id does not exist`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'405':
$ref: '#/components/responses/MethodNotAllowed'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
PageInfo:
type: object
description: Pagination information for paginated responses.
properties:
hasNextPage:
type: boolean
description: Indicates if there are more records available.
nextCursor:
type: string
nullable: true
description: Cursor for the next page of results. `null` if no more results.
pageSize:
type: integer
description: Number of records per page.
totalRecords:
type: integer
description: Total number of records matching the query.
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
MethodNotAllowed:
description: Method Not Allowed - Invalid HTTP method for this endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#personal-access-tokens-pat).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````