---
title: "Create schedule"
method: POST
path: "/api/v1/schedules"
tags: ["Schedules"]
---

# Create schedule

`POST /api/v1/schedules`

Create a new scheduled delivery for a dashboard. Required fields vary by destinationType (email, webhook, sftp, slack). For org API keys, use the userId query parameter to create the schedule on behalf of a specific user.

## Query parameters

- `userId` string, uuid — Membership ID of the user who should own the schedule (org API keys only). If not provided, the schedule is owned by the API key owner. User-scoped API keys cannot use this parameter.

## Request body

- object — Request body for creating a scheduled task. Required fields vary by destinationType.
  - `bucketName` string — S3 bucket name (S3 destination only). Must be 3-63 characters, lowercase.
  - `conditionQueryMapKey` string — The ID of the query to monitor for triggering an alert. Required if conditionType is provided.
  - `conditionType` 'RESULTS_CHANGED' | 'RESULTS_UNCHANGED' | 'RESULTS_PRESENT' | 'RESULTS_MISSING' — Defines the type of condition to use for alerts. Required if conditionQueryMapKey is provided.
  - `destinationType` 'email' | 'webhook' | 'sftp' | 'slack' | 's3', required — The delivery destination type
  - `enableFormatting` boolean — If true, formatting will be enabled in the output
  - `fanOut` boolean — If true, send personalized emails to each recipient (email only)
  - `filterConfig` unknown
  - `format` 'link_only' | 'pdf' | 'png' | 'csv' | 'xlsx' | 'json', required — The output format: link_only, pdf, png, csv, xlsx, json
  - `hideHiddenFields` boolean — If true, hidden fields won't be displayed (csv/xlsx only)
  - `hideTitle` boolean — If true, hide the title in output (pdf/png only)
  - `identifier` string, required — The ID of the dashboard to schedule
  - `keyPrefix` string — S3 key prefix / folder path (S3 destination only). Leading slashes are normalized.
  - `killJobsOnFailure` boolean — If true, stop entire job if any queries fail
  - `name` string, required — The name of the scheduled task
  - `recipients` object[] — Email recipients (email destination only). For Slack destinations, use the "recipients" field with a channel ID string or user ID(s) as a string or array.
    - `email` string, email, required — Recipient email address
  - `region` string — AWS region where the S3 bucket is located (S3 destination only).
  - `roleArn` string — ARN of the cross-account IAM role Omni will assume to write to the S3 bucket (S3 destination only).
  - `schedule` string, required — AWS EventBridge cron expression (minute hour day-of-month month day-of-week year)
  - `showContentLink` boolean — If true, include a link to the content
  - `showFilters` boolean — If true, show applied filters in output
  - `slackRecipientType` string — Slack recipient type (Slack destination only). Use "channel" to deliver to a single Slack channel, or "users" to deliver to one or more Slack users via direct message.
  - `testNow` boolean — If true, run immediately instead of scheduling
  - `timezone` string, required — IANA timezone for the schedule
  - `timezoneOverride` string, nullable — Optional IANA timezone applied to query execution at render time. Distinct from `timezone` (which controls *when* the schedule fires). Omit or pass null for no override.
  - `webhookUrl` string, uri — Webhook URL (webhook destination only)

## Response `200`

Schedule created successfully

- object — Create schedule response
  - `delivererRoleArn` string — The ARN of the Omni deliverer role. Use this as the Principal in your IAM role trust policy. Only returned for S3 destinations.
  - `externalId` string, uuid — The organization ID used as the external ID for confused deputy prevention. Add this to your IAM role trust policy as the sts:ExternalId condition. Static across all S3 destinations for your organization. Only returned for S3 destinations.
  - `id` string, uuid — Created schedule ID (only when testNow is false)
  - `message` string, required — Success message

## Other responses

- `400` — Invalid request body or filter configuration
- `401` — Authentication required
- `403` — Permission denied - cannot schedule this dashboard
- `404` — Dashboard not found

---

[API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/versions/de7cac8b5983/schema)