Skip to main content
POST

Downloading drafts

A draft’s unpublished content renders against the branch its currently on. Permissions and the download setting come from the published dashboard, whether you request the published version or a draft.

Authorizations

Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Path Parameters

dashboardId
string
required

The dashboard identifier (ID or document UUID). Accepts a published dashboard or one of its drafts.

Query Parameters

userId
string

The user ID to run the download as. Only valid when authenticating with an organization API key. Use the List users or List embed users endpoints to retrieve user IDs.

Body

application/json
format
enum<string>
required

Output format:

Available options:
pdf,
png,
csv,
xlsx,
json
filename
string

Custom filename for the downloaded file. Defaults to the dashboard name.

Maximum string length: 255
queryIdentifierMapKey
string

Tile identifier to download a single tile instead of the full dashboard. Required for XLSX and JSON formats if overrideRowLimit=true.

filterConfig
object

Dashboard filter values to apply before rendering

containerPages
string[]

Applicable to PDF, PNG, CSV, and XLSX formats, on dashboards using the advanced (multi-page) layout. The instanceKeys of the pages to render:

  • PDF renders the listed pages in storage order.
  • PNG accepts exactly one page.
  • CSV and XLSX keep only the tiles on the selected pages.

Not supported for json format, link_only, or together with queryIdentifierMapKey for a single-tile download. Defaults to the dashboard's first page for PDF and PNG, and to every tile for CSV and XLSX.

Minimum array length: 1
paperFormat
enum<string>
default:fit_page

Applicable to PDF and PNG formats. Page size.

Available options:
fit_page,
letter,
legal,
tabloid,
a3,
a4
paperOrientation
enum<string>

Applicable to PDF and PNG formats. Page orientation.

Available options:
portrait,
landscape
hideTitle
boolean
default:false

Applicable to PDF and PNG formats. If true, hide the dashboard title in the output.

showFilters
boolean
default:true

Applicable to PDF and PNG formats. If true, display applied filter values in the output.

expandAiSummaries
boolean

Compatible with pdf and png formats. If true, AI summary tiles grow to show their full text, splitting across pages when paperFormat isn't fit_page.

With paperFormat: fit_page, the page grows instead, and the operation fails if the page would be taller than 60,000px.

Example:

false

expandTablesToShowAllRows
boolean

Applicable to PDF and PNG formats. If true, expand table tiles to display all rows.

With paperFormat: fit_page, the page grows to fit the rows, and the download fails if the page would be taller than 60,000px.

singleColumnLayout
boolean

Applicable to PDF and PNG formats. If true, render tiles in a single column layout.

enableFormatting
boolean
default:false

Applicable to CSV, XLSX, and JSON formats. If true, preserve number and date formatting.

hideHiddenFields
boolean
default:false

Applicable to CSV and XLSX formats. If true, exclude hidden fields from the output.

overrideRowLimit
boolean
default:false

Applicable to CSV, XLSX, and JSON formats. Used with maxRowLimit. If true, remove the default row limit.

If true for XLSX and JSON formats, a queryIdentifierMapKey is required.

maxRowLimit
integer

Applicable to CSV, XLSX, and JSON formats. Maximum number of rows to export. Can be used with overrideRowLimit to export more rows than the default row limit.

Required range: 1 <= x <= 1000000
cache
enum<string>
default:Standard

Cache policy controlling how the download's queries use cached results. Must be one of:

  • Standard - Default. Standard caching behavior, including requerying cached result sets.
  • SkipRequery - Uses cached results if available, but does not requery cached result sets.
  • SkipCache - Bypasses the cache and always executes fresh queries.
Available options:
Standard,
SkipRequery,
SkipCache
useCache
boolean
deprecated

Deprecated. Use cache: SkipCache for fresh data.

Response

Download initiated successfully

job_id
string<uuid>

The job ID to use for checking status and downloading the file

message
string

Success message