Export data from a workbook

This endpoint lets you create a file containing data exported from a workbook, allowing you to retrieve large datasets or detailed reports 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 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 endpoint to download the requested file when it is ready. See Download an exported file.

Usage notes

• Retrieve the workbookId by calling the /v2/workbooks endpoint.
• The endpoint exports up to 1 million rows for 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.
• You can enable asynchronous processing of large data volumes with the useAsynchronously 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 report export: Based on an external set of conditions, export a report from Sigma.
• Data analysis: Export specific datasets 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

• Use the asynchronous export option for large datasets to avoid timeouts and ensure system stability.
• Clearly specify parameters to retrieve only the necessary data, optimizing performance and reducing network load.
• Check the status of asynchronous exports regularly and implement error handling to manage incomplete or failed exports gracefully.