Workbook Export API
This document explains how to use Sigma’s developer API for workbook exports.
At this time the workbook export endpoint can be used to export the entire workbook, a single workbook page or an individual element, per request.
- The entire workbook, workbook pages and elements can be exported to PDF type.
- Workbook pages and elements can be exported to PNG type.
- The data from Workbook elements can be exported to CSV, JSON, JSONL, or XLSX types.
As within the Sigma app, there is a 1 million row export limit for CSV/XLSX/JSON types. To export more rows, you can batch your requests in up to 1 million row chunks using the "rowLimit" and "offset" parameters. Or you can consider using another export method such as exporting to Cloud Storage which has a 5 GB size limit per export.
If your request is successful then Sigma will respond with a queryId to associate with your workbook export request. You will use this queryId as a reference for downloading the corresponding file using Sigma’s query download endpoint.
It can take an arbitrary amount of time for our system to process the file and have it ready to be downloaded. While the file is being processed, requests to the query download endpoint will respond with the status code 204 No Content.
For security and privacy reasons, by default the queryId expires 1 hour after your export request has been processed by our system and the file has become ready for download. But this default expiration time can be overridden for up to 6 hours by using the optional request parameter "resultsValidityTimeMs" detailed below.
For Sigma’s baseline workbook API, visit Workbook API.
Endpoints
POST /v2/workbooks/{workbookId}/export
Returns a workbook export query object based on a workbookId.
Try it in Swagger
GET /v2/workbooks/{workbookId}/schedules
This endpoint retrieves the schedules associated with a specific workbook.
POST /v2/workbooks/{workbookId}/schedules
This endpoint allows you to create a new schedule for a specific workbook.
Try it in Swagger
The Workbook Export Query Object
Attributes
jobComplete boolean
True if the job has completed prior to Sigma’s response. A false value doesn't indicate that the job failed; it means that the job is incomplete.
queryId string
A unique identifier for the resulting query. QueryId is used with Sigma’s Query API to download the workbook export.
{
"jobComplete": false,
"queryId": "b4841ad9-8d6f-4074-cf6e-afcbff6c390a"
}
scheduledNotificationId string
A unique identifier for the schedule notification.
workbookId string
The workbook’s unique identifier.
createdBy string
The unique identifier, memberId, of the organization member who created the workbook.
updatedBy string
The unique identifier, memberId, of the organization member who last modified changes to the workbook.
createdAt string
The timestamp at which the workbook was created.
updatedAt string
The timestamp at which the workbook was last modified.
Generate a Workbook Export Query
Returns a workbook export query object based on a workbookId.
POST /v2/workbooks/{workbookId}/export
Permissions
- The user account associated with the API token must have permission to export the workbook, workbook page, or workbook element.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Request Parameters
Note: Except for entire workbook export, you must include either elementId or pageId, depending on which you are exporting.
elementId string
The unique identifier of the element you want to export.
This element**Id corresponds to the nodeId in the Workbook's URL while the element is selected. If you select another element, or navigate to another page within the Workbook, you will see that this nodeId** changes.
This parameter is only used when exporting a specific element.
pageId string
The unique identifier of the page you want to export.
This pageId corresponds to the nodeId in the Workbook's URL when on that page with no element selected. If you select an element, or navigate to another page within the Workbook, you will see that this nodeId changes.
This parameter is only used when exporting a specific page.
format object
The export format you wish to use.
- The entire workbook can be exported to PDF.
- Workbook pages can be exported to PDF or PNG.
- Workbook elements can be exported to PNG and their data to CSV, JSON, JSONL, or XLSX
The specified format type must be entered within quotation marks and be in lowercase. For example:
"format": { \
"type": "csv" \
}
If the format type equals “pdf”, it is required to also include layout (i.e. portrait or landscape).
"format": { \
"type": "pdf", \
"layout": "landscape" \ }
If the format type equals “png”, you may optionally specify the width and height of the resulting image in pixel size. If these are not specified, our system will automatically generate a width and height that may differ from the page's or element's appearance inside the Sigma app.
"format": { \
"type": "png", \
"pixelWidth": 1000, \
"pixelHeight": 2000 \
}
Notes
As within the Sigma app, there is a 1 million row export limit for CSV/XLSX/JSON types. To export more rows, you can batch your requests in up to 1 million row chunks using the "rowLimit" and "offset" parameters. Or you can consider using another export method such as exporting to Cloud Storage which has a 5 GB size limit per export.
rowLimit number [optional]
The total number of rows to limit your CSV/XLSX/JSON type export to.
{ "rowLimit": 1000 }
offset number [optional]
The offset number of rows for your CSV/XLSX/JSON type export to start from.
{ "offset": 1001 }
resultsValidityTimeMs number [optional]
The time, in milliseconds, that you would like to override the default 1 hour queryId expiration to. The maximum time this can be overridden to is 6 hours (21600000 milliseconds).
For example, to extend the validity of the queryId by 4 hours you would set this parameter's value to 14400000 (4 * 3600 * 1000).
{ "resultsValidityTimeMs": 14400000 }
tag string [optional]
Specifies the Version Tag version of the Workbook to be exported.
{ "tag": "Production" }
exportAs string [optional]
Specifies the Member ID of the Sigma user whose credentials you want to run the export queries as, i.e. for Row-Level Security.
{ "exportAs": "7xtVWXPJqLptLezceRadESnwfttOP" }
parameter**s** object [optional]
A mapping of control IDs to your intended input values. Note that both workbook "parameter" and "filter" control types have control IDs that can be used.
Syntax:
{ parameter-id: parameter-value }
The parameter-id is the control ID of the "parameter" or "filter" control element in the workbook. The parameter-value is the value for that parameter/filter. Parameter/filter values can take multiple forms, depending on the different types.
Parameter/Filter Object Types
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 and semicolon.)
Text
- Single value: “some-text” | “:null” | “:empty”
- List of values: “some-text,more-text,:null,:empty” (No space after the comma.)
Date
- Fixed date: “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
- Formats supported (where: %Y: year, %m: month, %d: day, %H:hours, %M: minutes, %S: seconds):
- List of fixed date: “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]
- Range date: “min:2022-01-01T01:01:59,max:next-day-3” (No space after comma and semicolon.)
Notes
“:null” is a special value that denotes the null primitive value.
“:empty” is a special value that denotes the empty string “”.
You are able to use URL encoding to encode characters in your parameter/filter values (such as commas) to prevent our system from confusing them for separators.
e.g. "New York, NY,Boston, MA" can be encoded as "New York%2C NY,Boston%2C MA"
filters object [Deprecated]
Use the parameters object above even when your control's type is a "filter".
cURL Request
curl --location --request POST 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/export' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
{
"jobComplete": boolean,
"queryId": string
}
Example
Example Request:
curl --location --request POST 'https://api.sigmacomputing.com/v2/workbooks/{6tWWojYtpnpJqdqkNKAwS5}/export' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"elementId": "Mkaex5leIGcjlkQa5PqEw",
"resultsValidityTimeMs": 14400000,
"format": {
"type": "csv"
},
"parameters": {
"boolean-true-parameter": "true"
"boolean-false-parameter": "false"
"boolean-list-parameter": "true,false,:null"
"number-parameter": "10.54"
"number-list-parameter": "10.54,12.35,:null"
"number-range": "min:5.4,max:10.3"
"text-parameter": "east"
"text-empty-parameter": ":empty"
"text-list-parameter": "east,west,:null,:empty"
"fixed-date-parameter-day": "2022-01-01"
"fixed-date-parameter-minute": "2022-01-01T01:01"
"fixed-date-parameter-sec": "2022-01-01T01:01:59"
"relative-prior-date-parameter": "prior-day-3"
"relative-next-date-parameter": "next-year-5"
"date-list-parameter": "2022-01-01,2022-01-05,2022-01-08,:null"
"date-range-parameter": "min:2022-01-01,max:2022-01-05"
"date-range-parameter": "min:prior-day-3,max:next-year-5"
}
}'
Example Response:
{
"jobComplete": false,
"queryId": "b4841ad9-8d6f-4074-cf6e-afcbff6c390a"
}
Return schedules for a workbook
GET /v2/workbooks/{workbookId}/schedules
Permissions
- You have access to the workbooks available in Sigma to the user account associated with the API access token.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
workbookId | string (required)
The unique identifier of the workbook.
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/workbooks/{workbookId}/schedules' \
--header 'Authorization: Bearer {access_token}'
Response
[
{
"scheduledNotificationId": "string",
"workbookId": "string",
"createdBy": "string",
"updatedBy": "string",
"createdAt": "1970-01-01T00:00:00.000Z",
"updatedAt": "1970-01-01T00:00:00.000Z"
}
]
Create a workbook schedule
This endpoint allows you to create a new workbook schedule.
POST/v2/workbooks/{workbookId}/schedules
Permissions
- You must be a Creator or Admin in your org.
Path Parameters
workbookId string [required]
The workbook’s unique identifier.
cURL Request
curl -X POST "https://api.sigmacomputing.com/v2/workbooks//schedules" \
-H "accept: application/json"\
-H "content-type: application/json" \
-d '{"target":[{"userId":"string","teamId":"string","email":"string","slackChannelName":"string","googleSpreadsheetUrl":"string","googleDriveFolderUrl":"string"}],"schedule":{"cronSpec":"string","timezone":"string"},"config":{"formatOptions":{"type":"CSV","rowLimit":0},"title":"string","messageBody":"string","includeLink":false,"runAsRecipient":false,"rowLimit":0,"chartId":"string"},"description":"string"}' \
Request Body
{
"target": [
{
"userId": "string",
"teamId": "string",
"email": "string",
"slackChannelName": "string",
"googleSpreadsheetUrl": "string",
"googleDriveFolderUrl": "string"
}
],
"schedule": {
"cronSpec": "string",
"timezone": "string"
},
"config": {
"formatOptions": {
"type": "CSV",
"rowLimit": 0
},
"title": "string",
"messageBody": "string",
"includeLink": false,
"runAsRecipient": false,
"rowLimit": 0,
"chartId": "string"
},
"description": "string"
}
Response
{
"scheduledNotificationId": "string",
"workbookId": "string",
"createdBy": "string",
"updatedBy": "string",
"createdAt": "1970-01-01T00:00:00.000Z",
"updatedAt": "1970-01-01T00:00:00.000Z"
}
Updated 5 months ago