v4

latestOpenAPI 3.1.02026-08-01207318738.7 KB

Schedules

Create schedule

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.

post/api/v1/schedules

Query parameters

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

Example:987fcdeb-51a2-43d7-9b56-254415f67890

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

bucketNamestring

S3 bucket name (S3 destination only). Must be 3-63 characters, lowercase.

conditionQueryMapKeystring

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

enableFormattingboolean

If true, formatting will be enabled in the output

fanOutboolean

If true, send personalized emails to each recipient (email only)

{"stackTrail":"paths:/api/v1/schedules:post:requestBody:content:application/json:schema:properties:filterConfig","oasType":"schema","type":"unknown","description":"Filter conditions to apply to the task","example":{"status":["active","pending"]}}

format'link_only' | 'pdf' | 'png' | 'csv' | 'xlsx' | 'json' required

The output format: link_only, pdf, png, csv, xlsx, json

hideHiddenFieldsboolean

If true, hidden fields won't be displayed (csv/xlsx only)

hideTitleboolean

If true, hide the title in output (pdf/png only)

identifierstring required

The ID of the dashboard to schedule

keyPrefixstring

S3 key prefix / folder path (S3 destination only). Leading slashes are normalized.

killJobsOnFailureboolean

If true, stop entire job if any queries fail

namestring required

The name of the scheduled task

regionstring

AWS region where the S3 bucket is located (S3 destination only).

roleArnstring

ARN of the cross-account IAM role Omni will assume to write to the S3 bucket (S3 destination only).

schedulestring required

AWS EventBridge cron expression (minute hour day-of-month month day-of-week year)

showContentLinkboolean

If true, include a link to the content

showFiltersboolean

If true, show applied filters in output

slackRecipientTypestring

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.

testNowboolean

If true, run immediately instead of scheduling

timezonestring required

IANA timezone for the schedule

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

webhookUrlstring uri

Webhook URL (webhook destination only)

Example request

{
  "bucketName": "my-reports-bucket",
  "conditionQueryMapKey": "Jmn2r3KV",
  "conditionType": "RESULTS_PRESENT",
  "destinationType": "email",
  "filterConfig": {
    "status": [
      "active",
      "pending"
    ]
  },
  "format": "pdf",
  "identifier": "12db1a0a",
  "keyPrefix": "reports/weekly/",
  "name": "Weekly Sales Report",
  "recipients": [
    {
      "email": "user@example.com"
    }
  ],
  "region": "us-east-1",
  "roleArn": "arn:aws:iam::123456789012:role/OmniS3DeliveryRole",
  "schedule": "0 9 ? * MON *",
  "showContentLink": true,
  "showFilters": true,
  "slackRecipientType": "channel",
  "timezone": "America/New_York",
  "timezoneOverride": "Europe/Paris",
  "webhookUrl": "https://example.com/webhook"
}

Response

Schedule created successfully

delivererRoleArnstring

The ARN of the Omni deliverer role. Use this as the Principal in your IAM role trust policy. Only returned for S3 destinations.

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

idstring uuid

Created schedule ID (only when testNow is false)

messagestring required

Success message

Example response

{
  "delivererRoleArn": "arn:aws:iam::529831494235:role/OmniSchedulerDelivererRole",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "Successfully created schedule"
}