---
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`

## Request

- Base URL: `https://blobsrus.omniapp.co/api`
- URL: `https://blobsrus.omniapp.co/api/v1/dashboards/{dashboardId}/download`
- Auth: HTTP bearer

Start an asynchronous download job for a published dashboard, a dashboard draft, 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 | For tiles with subtotal or grand total rows, one dimension cell in each totals row is labeled `Total` | | CSV | Yes (as ZIP) | Yes | For full dashboards, delivery will be a zip file containing one CSV per tile. For tiles with subtotal or grand total rows, one dimension cell in each totals row is labeled `Total` | | 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
  - `containerPages` string[]: **Applicable to PDF, PNG, CSV, and XLSX formats, on dashboards using the advanced (multi-page) layout.** The `instanceKey`s 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.
  - `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.
  - `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.
  - `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: **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.
  - `cache` 'Standard' | 'SkipRequery' | 'SkipCache': 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.
  - `useCache` boolean: Deprecated. Use `cache: SkipCache` for fresh data.

## 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 - `Invalid page found in containerPages: <page>. Available pages are: <id> (<name>), ...` - `PNG format supports only one page` - `containerPages can only be used with PDF, PNG, CSV or Excel formats` — also returned when `containerPages` is used on a dashboard that doesn't use the advanced (multi-page) layout - 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)

## Changes

- **2026-11-03** `43290040f88f`: 4 info
  - added the new optional request property `cache`
  - added the new optional request property `containerPages`
  - added the new optional request property `expandAiSummaries`
  - added the new optional request property `useCache`

[Operation history](https://skmtc.dev/omni/apis/omni-api/changes/v1/dashboards/:dashboardId/download/post.md)

---

[API](https://skmtc.dev/omni/apis/omni-api.md) - [All operations](https://skmtc.dev/omni/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omni/apis/omni-api/revisions/43290040f88f?raw)