---
title: "Initiate dashboard or tile download"
method: POST
path: "/v1/dashboards/{dashboardId}/download"
tags: ["Dashboard downloads"]
---

# Initiate dashboard or tile download

`POST /v1/dashboards/{dashboardId}/download`

Start an asynchronous download job for a dashboard or single tile with support for multiple output formats. After starting a job, poll [Check download status](/api/dashboard-downloads/check-download-status) for completion, then retrieve the file from [Download file](/api/dashboard-downloads/download-file).

<Note>
  Only one download per dashboard per user is allowed at a time. If a download is already in progress for the specified dashboard, the request will return a `409 Conflict` response with the existing job ID.
</Note>

## Path parameters

- `dashboardId` string, required

## Query parameters

- `userId` string

## Request body

- object
  - `format` 'pdf' | 'png' | 'csv' | 'xlsx' | 'json', required — Output format: | Format | Full dashboard | Single tile | Notes | |--------|----------------|-------------|-------| | PDF | Yes | Yes | | | PNG | Yes | Yes | | | XLSX | Yes | Yes | | | CSV | Yes (as ZIP) | Yes | For full dashboards, delivery will be a zip file containing one CSV per tile | | JSON | No | Yes | Only single tile is supported. Requires `queryIdentifierMapKey` to be specified. |
  - `filename` string — Custom filename for the downloaded file. Defaults to the dashboard name.
  - `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
  - `paperFormat` 'fit_page' | 'letter' | 'legal' | 'tabloid' | 'a3' | 'a4' — **Applicable to PDF and PNG formats**. Page size.
  - `paperOrientation` 'portrait' | 'landscape' — **Applicable to PDF and PNG formats**. Page orientation.
  - `hideTitle` boolean — **Applicable to PDF and PNG formats**. If `true`, hide the dashboard title in the output.
  - `showFilters` boolean — **Applicable to PDF and PNG formats**. If `true`, display applied filter values in the output.
  - `expandTablesToShowAllRows` boolean — **Applicable to PDF and PNG formats**. If `true`, expand table tiles to display all rows.
  - `singleColumnLayout` boolean — **Applicable to PDF and PNG formats**. If `true`, render tiles in a single column layout.
  - `enableFormatting` boolean — **Applicable to CSV, XLSX, and JSON formats**. If `true`, preserve number and date formatting.
  - `hideHiddenFields` boolean — **Applicable to CSV and XLSX formats**. If `true`, exclude hidden fields from the output.
  - `overrideRowLimit` boolean — **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.

## Response `200`

Download initiated successfully

- object
  - `job_id` string, uuid — The job ID to use for checking status and downloading the file
  - `message` string — Success message

## Other responses

- `400` — Bad Request. Possible causes: - Missing required `format` field - Invalid format value - Invalid options for the specified format - Malformed JSON body - Invalid UUID format
- `403` — Insufficient permissions to download the specified dashboard
- `404` — Dashboard not found
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint
- `409` — A download is already in progress for the specified dashboard
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

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