---
title: "Export data from a workbook"
method: POST
path: "/v2/workbooks/{workbookId}/export"
tags: ["Workbooks"]
---

# Export data from a workbook

`POST /v2/workbooks/{workbookId}/export`

## Request

- Base URL: `https://api.sigmacomputing.com`
- URL: `https://api.sigmacomputing.com/v2/workbooks/{workbookId}/export`
- Auth: HTTP bearer

This endpoint lets you create a file containing data exported from a workbook, allowing you to retrieve large sets of data in a structured format. Export the entire workbook, a single workbook page, or an individual element. You can specify parameters to filter the data and format options for the file.

Different file formats, including CSV, PDF, JSON, and others,  are supported for different export choices. See [Send or schedule workbook exports](/docs/send-or-schedule-workbook-exports) for details on supported formats for different types of exports.

Successful requests to the endpoint return a queryId. Use the **queryId** with the [/v2/query/{queryId}/download](https://help.sigmacomputing.com/reference/download-query) endpoint to download the requested file when it is ready. See [Download an exported file](https://help.sigmacomputing.com/reference/download-query).

## Usage notes
- Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint.
- This endpoint is rate limited to 400 requests per minute.
- This endpoint exports up to 1 million rows for CSV/XLSX/JSON file formats. You can export more rows if you batch your requests in chunks of up to 1 million rows. Use the `rowLimit` parameter to specify the size of the chunk and the `offset` parameter to specify the row to start the next chunk from. For example, if you specify a rowLimit of 2500, to export the next chunk of 2500 rows, specify an offset of 2501. The order of the data matches the order in the data element when the request is made, so there is a possibility of data overlap between requests.
- For security and privacy reasons, the `queryId` used to download the exported data expires 1 hour after your request is received and the file becomes available to download. You can extend this default expiration to 6 hours using the `resultsValidityTimeMs` request parameter.
- When exporting a PNG file, the `pixelWidth` and `pixelHeight` parameters are respected on a best effort basis and the output might not match the requested dimensions.

## Usage scenarios
- Conditional workbook export: Based on an external set of conditions, export a workbook from Sigma.
- Data analysis: Export specific sets of data for offline analysis, leveraging tools that might not connect directly to a data warehouse.
- Integration: Integrate enriched and analyzed data with other applications, providing the necessary data in a format that these applications can process.

## Best practices
- Clearly specify parameters to retrieve only the necessary data, optimizing performance and reducing network load.

## Path parameters

- `workbookId` string, required

## Request body

- union
  - WorkbooksExportWorkbookRequest0: Export a specific element
    - `elementId` string, required
    - `format` union, required
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf0Format0: Export options for csv, json, jsonl, xlsx
        - `type` 'csv' | 'jsonl' | 'json' | 'xlsx', required
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf0Format1: Export options for PDF
        - `type` 'pdf', required
        - `layout` 'portrait' | 'landscape', required
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf0Format2: Export options for PNG
        - `type` 'png', required
        - `pixelWidth` number, double
        - `pixelHeight` number, double
    - `parameters` object: Specify the control ID and control value of one or more control elements in the workbook or report to filter the returned data. The control must exist in the Sigma workbook or report and target an element before you can export based on the control value. **Syntax** { control-id: control-value } The control-id is configured in the Sigma workbook or report. The control-value is the value that is passed to the control. Values can take multiple forms, depending on the data type of the control: **Boolean** - Single value: "true" | "false" | ":null" - List of Boolean: "true,false,:null" (No space after the comma.) **Number** - Single value: "10.54", ":null" - List of values: "10.54,23.45,:null" (No space after the comma.) - Range of numbers: "min:10.54,max:23.45" (No space after the comma or colon.) **Text** - Single value: "some-text" | ":null" | ":empty" - List of values: "some-text,more-text,:null,:empty" (No space after the comma.) **Date** All dates use UTC time zones. - Fixed date using ISO-6801 format: "2022-01-01T01:01:59" | ":null" - Formats supported (where: %Y: year, %m: month, %d: day, %H:hours, %M: minutes, %S: seconds): - %Y-%m-%d - %Y-%m-%dT%H:%M - %Y-%m-%dT%H:%M:%S - List of fixed dates: "2022-01-01T01:01:59,2022-02-02T02:02:59,:null" - Relative date: "prior-day-3" | "next-day-3" - Format: [prior|next]-[year|quarter|month|week|isoWeek|day|hour|minute]-[number] - Date range: "min:2022-01-01T01:01:59,max:next-day-3" (No spaces after the comma or colon.) - Leave max blank for "on or after" and min blank for "on or before", for example: - "Date-Range": "min:2020-04-01,max:" - "Date-Range": "min:,max:next-day-3" **Notes** - ":null" is a special value that denotes the null primitive value. - ":empty" is a special value that denotes the empty string "". Use [URL encoding](https://help.sigmacomputing.com/docs/special-characters-for-url-parameters) to encode characters in your control values (such as commas) to prevent the system from interpreting them as separators. For example: "New York, NY,Boston, MA" can be encoded as: "New%20York%2C%20NY,Boston%2C%20MA"
    - `timeout` number, double
    - `tag` string: Specifies the version tag of the workbook to be exported.
    - `exportAs` string: Specifies the user ID of the Sigma user to run the export queries as, such as to enforce row-level security. Not supported for users who access Sigma with OAuth.
    - `rowLimit` number, double: Total number of rows to limit a CSV/XLSX/JSON-formatted export to.
    - `offset` number, double: The offset number of rows for a CSV/XLSX/JSON-formatted export to start from.
    - `language` 'de' | 'en' | 'es' | 'fr' | 'it' | 'ja' | 'pl' | 'pt' | 'ru' | 'th' | 'en-au' | 'en-ca' | 'en-gb' | 'en-ie' | 'es-mx' | 'fr-ca' | 'ko-kr' | 'nl-nl' | 'pt-br' | 'sv-se' | 'tr-tr' | 'zh-cn' | 'zh-tw': The locale identifier corresponding to the language of the translation.
    - `languageVariant` string: The name of the custom translation variant.
  - WorkbooksExportWorkbookRequest1: Export a page of a workbook
    - `pageId` string, required: Identifier of the workbook page.
    - `format` union, required
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf1Format0: Export options for PDF documents
        - `type` 'pdf', required
        - `layout` 'portrait' | 'landscape', required
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf1Format1: Export options for PNG documents
        - `type` 'png', required
        - `pixelWidth` number, double
        - `pixelHeight` number, double
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf1Format2: Export options for EXCEL documents
        - `type` 'xlsx', required
    - `parameters` object: Specify the control ID and control value of one or more control elements in the workbook or report to filter the returned data. The control must exist in the Sigma workbook or report and target an element before you can export based on the control value. **Syntax** { control-id: control-value } The control-id is configured in the Sigma workbook or report. The control-value is the value that is passed to the control. Values can take multiple forms, depending on the data type of the control: **Boolean** - Single value: "true" | "false" | ":null" - List of Boolean: "true,false,:null" (No space after the comma.) **Number** - Single value: "10.54", ":null" - List of values: "10.54,23.45,:null" (No space after the comma.) - Range of numbers: "min:10.54,max:23.45" (No space after the comma or colon.) **Text** - Single value: "some-text" | ":null" | ":empty" - List of values: "some-text,more-text,:null,:empty" (No space after the comma.) **Date** All dates use UTC time zones. - Fixed date using ISO-6801 format: "2022-01-01T01:01:59" | ":null" - Formats supported (where: %Y: year, %m: month, %d: day, %H:hours, %M: minutes, %S: seconds): - %Y-%m-%d - %Y-%m-%dT%H:%M - %Y-%m-%dT%H:%M:%S - List of fixed dates: "2022-01-01T01:01:59,2022-02-02T02:02:59,:null" - Relative date: "prior-day-3" | "next-day-3" - Format: [prior|next]-[year|quarter|month|week|isoWeek|day|hour|minute]-[number] - Date range: "min:2022-01-01T01:01:59,max:next-day-3" (No spaces after the comma or colon.) - Leave max blank for "on or after" and min blank for "on or before", for example: - "Date-Range": "min:2020-04-01,max:" - "Date-Range": "min:,max:next-day-3" **Notes** - ":null" is a special value that denotes the null primitive value. - ":empty" is a special value that denotes the empty string "". Use [URL encoding](https://help.sigmacomputing.com/docs/special-characters-for-url-parameters) to encode characters in your control values (such as commas) to prevent the system from interpreting them as separators. For example: "New York, NY,Boston, MA" can be encoded as: "New%20York%2C%20NY,Boston%2C%20MA"
    - `timeout` number, double
    - `tag` string: Specifies the version tag of the workbook to be exported.
    - `exportAs` string: Specifies the user ID of the Sigma user to run the export queries as, such as to enforce row-level security. Not supported for users who access Sigma with OAuth.
    - `rowLimit` number, double: Total number of rows to limit a CSV/XLSX/JSON-formatted export to.
    - `offset` number, double: The offset number of rows for a CSV/XLSX/JSON-formatted export to start from.
    - `language` 'de' | 'en' | 'es' | 'fr' | 'it' | 'ja' | 'pl' | 'pt' | 'ru' | 'th' | 'en-au' | 'en-ca' | 'en-gb' | 'en-ie' | 'es-mx' | 'fr-ca' | 'ko-kr' | 'nl-nl' | 'pt-br' | 'sv-se' | 'tr-tr' | 'zh-cn' | 'zh-tw': The locale identifier corresponding to the language of the translation.
    - `languageVariant` string: The name of the custom translation variant.
  - WorkbooksExportWorkbookRequest2: Export an entire workbook
    - `format` union, required
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf2Format0: Export options for PDF documents
        - `type` 'pdf', required
        - `layout` 'portrait' | 'landscape', required
      - V2WorkbooksWorkbookIdExportPostRequestBodyContentApplicationJsonSchemaOneOf2Format1: Export options for EXCEL documents
        - `type` 'xlsx', required
    - `parameters` object: Specify the control ID and control value of one or more control elements in the workbook or report to filter the returned data. The control must exist in the Sigma workbook or report and target an element before you can export based on the control value. **Syntax** { control-id: control-value } The control-id is configured in the Sigma workbook or report. The control-value is the value that is passed to the control. Values can take multiple forms, depending on the data type of the control: **Boolean** - Single value: "true" | "false" | ":null" - List of Boolean: "true,false,:null" (No space after the comma.) **Number** - Single value: "10.54", ":null" - List of values: "10.54,23.45,:null" (No space after the comma.) - Range of numbers: "min:10.54,max:23.45" (No space after the comma or colon.) **Text** - Single value: "some-text" | ":null" | ":empty" - List of values: "some-text,more-text,:null,:empty" (No space after the comma.) **Date** All dates use UTC time zones. - Fixed date using ISO-6801 format: "2022-01-01T01:01:59" | ":null" - Formats supported (where: %Y: year, %m: month, %d: day, %H:hours, %M: minutes, %S: seconds): - %Y-%m-%d - %Y-%m-%dT%H:%M - %Y-%m-%dT%H:%M:%S - List of fixed dates: "2022-01-01T01:01:59,2022-02-02T02:02:59,:null" - Relative date: "prior-day-3" | "next-day-3" - Format: [prior|next]-[year|quarter|month|week|isoWeek|day|hour|minute]-[number] - Date range: "min:2022-01-01T01:01:59,max:next-day-3" (No spaces after the comma or colon.) - Leave max blank for "on or after" and min blank for "on or before", for example: - "Date-Range": "min:2020-04-01,max:" - "Date-Range": "min:,max:next-day-3" **Notes** - ":null" is a special value that denotes the null primitive value. - ":empty" is a special value that denotes the empty string "". Use [URL encoding](https://help.sigmacomputing.com/docs/special-characters-for-url-parameters) to encode characters in your control values (such as commas) to prevent the system from interpreting them as separators. For example: "New York, NY,Boston, MA" can be encoded as: "New%20York%2C%20NY,Boston%2C%20MA"
    - `timeout` number, double
    - `tag` string: Specifies the version tag of the workbook to be exported.
    - `exportAs` string: Specifies the user ID of the Sigma user to run the export queries as, such as to enforce row-level security. Not supported for users who access Sigma with OAuth.
    - `rowLimit` number, double: Total number of rows to limit a CSV/XLSX/JSON-formatted export to.
    - `offset` number, double: The offset number of rows for a CSV/XLSX/JSON-formatted export to start from.
    - `language` 'de' | 'en' | 'es' | 'fr' | 'it' | 'ja' | 'pl' | 'pt' | 'ru' | 'th' | 'en-au' | 'en-ca' | 'en-gb' | 'en-ie' | 'es-mx' | 'fr-ca' | 'ko-kr' | 'nl-nl' | 'pt-br' | 'sv-se' | 'tr-tr' | 'zh-cn' | 'zh-tw': The locale identifier corresponding to the language of the translation.
    - `languageVariant` string: The name of the custom translation variant.

## Response `200`

The response body.

- WorkbooksExportWorkbookResponse200
  - `jobComplete` boolean, required
  - `queryId` string, required
  - `rows` object[]
  - `message` string

---

[API](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api.md) - [All operations](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/revisions/fb6036208c49?raw)