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. 

Summary of Content

Endpoints
The Workbook Export Query Object
Attributes
Generate a Workbook Export Query
Permissions
Request Parameters
cURL Request
Response
Example
Return Schedules for a Workbook
Create a Workbook Schedule
Related Resources

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.

Try it in Swagger

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

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

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

 

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.)
    • leave max blank for "on or after" and min blank for "on or before" ie
      • "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 “”.

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

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

Was this page helpful?
Yes No