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

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. (Note that JSON type exports do not require this second step and the JSON data will be returned in response to your export request).

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

Summary of Content

Endpoints
The Workbook Export Query Object
Attributes
Generate a Workbook Export Query
Permissions
Request Parameters
cURL Request
Response
Example
Related Resources

Endpoints

POST /v2/workbooks/{workbookId}/export

      Returns a workbook export query object based on a workbookId.
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. 

rows Array<Object> | undefined

A list of objects, each representing a row with {column name: value} {key: value} pairs. 
Important: This attribute is only available when the requested "format" is "json".

{
 "jobComplete": false,
  "queryId": "b4841ad9-8d6f-4074-cf6e-afcbff6c390a"
}

 

Generate a Workbook Export Query

Returns a workbook export query object based on a workbookId.

POST /v2/workbooks/{workbookId}/export

Try it in Swagger

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

If the format type is JSON, the response body will include an additional attribute "rows" which lists column data by row.

If the format type equals “pdf”, also include layout (i.e. portrait or landscape).

{ "type": "pdf", "layout": "landscape" }

 

resultsValidityTimeMs number [optional]

The time, in milliseconds, that you would like to override the default 1 hour queryId expiration. 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 }

 

timeout number [optional]

The time limit, in seconds, that you would like to set on your request.

This is used for JSON exports only. If your export format is not JSON, or if timeout is excluded, a response will be returned immediately.  

  

parameters 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
      
  • 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 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"
}

Related Resources

API Documentation

Get Started with Sigma's API
Create an API Token and Client Id
Workbook API
Query API
Workbook Schema API
Identify Unique Ids in Sigma

Product Documentation

Send and Schedule Workbooks
Download a Data Element