exports

Create an export schedule for a dashboard.

Creates a new recurring export subscription for the dashboard (ADR-0051, DVT-726). Requires dashboard:write. Supply either a raw 5-field cron expression or a preset object — not both. The cron is validated server-side; timezone must be a valid IANA timezone name. next_run_at is computed from (cron, timezone) in the same transaction. Destinations (Slack webhooks) are deferred to DVT-729 — a body with destinations is accepted but ignored (field is reserved for that ticket) for pdf/png; on xlsx/csv a non-empty destinations is rejected with a 400 (xlsx/csv are email-only).

A timezone that cannot be resolved to an IANA zone is a 422 (DVT-4321), not a 400; the failing value is echoed in a timezone extension field. A blank timezone, or "Local", normalizes to UTC rather than being rejected.

post/v1/dashboards/{id}/export-schedules

Request

  • Base URL: http://localhost:8080
  • URL: http://localhost:8080/v1/dashboards/{id}/export-schedules
  • Auth: one of:
    • API key in cookie dvt_session
    • HTTP bearer

Request body

titlestring

Optional human-readable label for this schedule.

cronstring

A canonical 5-field cron expression (validated server-side).

timezonestring

IANA timezone name (e.g. "America/New_York"). Defaults to UTC. A blank value, or "Local", normalizes to "UTC"; any other name that cannot be resolved is a 422.

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

Output format for the exported artifact. xlsx and csv export one table panel's rows (DVT-5200): they require panelId of a table panel (rows capped at 10,000; xlsx carries a truncation note). Scheduled exports never include sheet panel rows (ADR-0091 I10); a sheet panel is rejected with 400 (point a table panel at the sheet's warehouse table instead). xlsx/csv egress warehouse rows, so creating or editing one requires data:query and data:export (403 without both; the free plan has neither). They are never stored: the file is built in memory and attached to the email only (a file over the 8 MiB attachment limit fails the run). They are therefore email-only — a non-empty destinations field in the request body (an undeclared field, ignored for pdf/png) on an xlsx/csv schedule is a 400.

panelIdstring nullable

When set, scopes this schedule to a single dashboard panel (element-grain export, ADR-0051 r2 §8). Supported with format: png, or xlsx/csv for a table panel (required for those formats; sheet and other panel types return 400); supplying panelId with format: pdf returns 400. The panel must exist in the dashboard's current spec; a nonexistent id returns 400 (UX guard — fire-time re-check is DVT-862). null or absent means whole-dashboard export (the default).

pageIdstring nullable

When set, scopes this schedule to a single dashboard page (page-grain export, DVT-1193). Holds the page slug from the spec (stable across page reorders); the runner resolves it to the current page index at fire time. Supported with both formats. Mutually exclusive with panelId — supplying both returns 400. The page must exist in the dashboard's current multi-page spec (single-page dashboards have no addressable pages); a nonexistent slug returns 400. null or absent means whole-dashboard export (the default).

Example request

{
  "cron": "0 9 * * 1"
}

Response

Schedule created.

Changes

No recorded changes to this operation across all 1 revision of this API.