Export data from a workbook

post

https://api.sigmacomputing.com/v2/workbooks/{workbookId}/export

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

workbookId

string

required

Unique identifier of the workbook.

Body Params

The request body.

Export a specific element

elementId

string

required

format

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

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

Total number of rows to limit a CSV/XLSX/JSON-formatted export to.

offset

number

The offset number of rows for a CSV/XLSX/JSON-formatted export to start from.

Responses

200The response body.

default