renders

Request a render of the dashboard.

Queues a PNG/PDF render of the dashboard (ADR-0024) and returns 202 with the render record; poll GET …/renders/{renderId} for status and the artifact URL. The revision is pinned at request time (default: the dashboard's current version), so the artifact is reproducible. Any org member may render a dashboard they can view; render sessions themselves may not. Returns 503 problem type render-unavailable while no render service is configured on the instance. The per-org hourly budget is operator-configurable (RENDER_RATE_LIMIT; default 10/hour on SaaS, no hourly cap in the native app).

Native app (DVT-1364, exportDelivery: render_app_stage): the API renders and stores the artifact write-once on the app-owned stage @app_spcs.renders; the succeeded record's url is the app-authenticated GET …/renders/{renderId}/artifact route (no signed URL), and renders are listed only to their requester. A 429 with Retry-After there also means too many renders are in flight on this app instance.

post/v1/dashboards/{id}/renders

Request

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

Request body

purpose'validation'

Async renders only (DVT-1364); rejected on /renders/inline. Only accepted in the Snowflake native app (render_app_stage) — a non-native-app deployment 400s regardless of caller role, since source='validation' is not a retention category there. validation stores the render as an expiring release-check render (deleted after RENDER_VALIDATION_RETENTION_HOURS, default 24) instead of a personal user render (which expires after RENDER_USER_RETENTION_HOURS, default the validation TTL); in the native app it additionally requires the admin-ranked render:validate capability (403 for a non-admin caller there). Any other value is 400.

format'png' | 'pdf'
revisioninteger

Dashboard revision to render. Default — the current version, pinned at request time.

widthinteger

Viewport width in px.

heightinteger

Viewport height in px.

pageinteger

Zero-indexed page of a multi-page dashboard to capture. Default 0 (the first page); single-page dashboards ignore it. An in-range value past the last page clamps to the last page. Each render captures one page — to capture every page, request a render per page index.

panelIdstring

Optional panel id to render in isolation (DVT-860). When provided, the artifact captures only the named panel rather than the full page; the R2 key gains an -el-<enc> segment so panel artifacts never collide with whole-page artifacts. The artifact's own dimensions are the PANEL's, not the viewport's (DVT-4358): the panel is laid out edge-to-edge at width and the capture is clipped to its bounding box, so a PNG comes back width × 2 (the capture device pixel ratio) wide and as tall as the panel. height sizes only the viewport the panel is laid out in — it does not bound the image. Do not assume width × height × 2. The server validates only that the value is non-empty; panel-id resolution against the dashboard spec happens in the render page (client-side). If the id does not match any panel, the render will transition to failed rather than returning a 4xx error. When absent, the whole page is rendered (existing behavior, byte-identical artifact key).

includeSummaryboolean

Only honored by POST /renders/inline (DVT-4428); ignored by the async createRender. When true, the 200 response is a JSON envelope carrying the image plus a machine-readable per-panel render summary, instead of raw artifact bytes — lets an agent verify a render (e.g. "drew 0 points") without a vision read of the image alone. Default false, byte-identical to today's behavior.

Response

Render queued.

Changes

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