Liveboard data API

Liveboard data API

To retrieve data related to a Liveboard or visualization from the ThoughtSpot system, you can use the Liveboard data API.

Using this API, you can fetch the following information:

  • All the visualization objects on a Liveboard

  • A specific or a group of visualizations on a Liveboard

Note

ThoughtSpot recommends using Liveboard data API to embed ThoughtSpot content within a native mobile app.

Supported operations🔗

API endpointAvailable from

POST /tspublic/v1/pinboarddata
Gets Liveboard object data from the ThoughtSpot application.

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 6.0.x

Required permissions🔗

You must have at least view access to the Liveboard and visualization objects.

Request URL🔗

POST /tspublic/v1/pinboarddata

Request parameters🔗

Query parameterDescription

id

String. The GUID of the Liveboard.

vizid Optional

String. A JSON array of GUIDs of the visualizations.

transient_pinboard_content

String. If the Liveboard has unsaved changes, pass this parameter in the browser fetch request.

batchsize

Integer. The batch size for loading Liveboard objects. The system default is -1.

pagenumber

Integer. An alternate way to define the offset. The system default is -1. The offset attribute definition will not apply if the pagenumber value is greater than 0.

offset

Integer. The system default is -1. You can set an offset value based on the following formula:

PageNumber (Offset) = PageNumber -1 * BatchSize

For example, if a Liveboard has 10 charts and each chart has 5 columns and 10 records, and the offset value is set to 1, the charts will display data from the second record onwards. If the pagenumber attribute is set to 3 and batchsize is defined as 1, then the offset value changes to 2, and all 10 charts will display data from the third record onwards.

formattype

String. Valid values are COMPACT or FULL JSON. The system default is COMPACT.

Liveboard data with unsaved changes🔗

To download or retrieve a Liveboard with unsaved changes, pass the transient_pinboard_content script with getExportRequestForCurrentPinboard method in the browser fetch request.

function getExportRequestForCurrentPinboard(frame: HTMLIframeElement): Promise<string>;

The promise returned resolves to a string that contains the transient Liveboard content, which is encoded as JSON and is sent to the Liveboard API endpoint with the transient content key. This content resembles the current Liveboard as is, including the unsaved changes if any, including unsaved changes to the following:

  • Liveboard filters

  • Runtime filters applied on visualizations on a Liveboard

  • Liveboard layout

If the new Liveboard experience is enabled, the transient content includes ad hoc changes to visualizations such as sorting, toggling of legends, and data drill down.

Sample browser fetch request🔗

< iframe src = "https://ts_host:port/" id = "ts-embed" > < /iframe>
< script src = "/path/to/liveboard.js" > < /script>
< script >
    const embed = new LiveboardEmbed("#embed", {
        frameParams: {},
    });
    async function liveboardData() {
    const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard);
    const liveboardDataResponse = await fetch("https://ts_host:port/callosum/v1/tspublic/v1/pinboarddata", {
        method: "POST",
        body: createFormDataObjectWith({
            "formattype": "COMPACT",
            "transient_pinboard_content": transientPinboardContent,
        }),
    });
 }
< /script>

Example requests🔗

Liveboard data🔗

CURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=f4533461-caa5-4efa-a189-13815ab86770&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=f4533461-caa5-4efa-a189-13815ab86770&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT

Visualization data🔗

CURL
curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot'
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=bea79810-145f-4ad0-a02c-4177a6e7d861&vizid=['fa934657-e347-4de7-b02d-3b46609233cc','62f98ad3-6ddd-4aed-8f13-58054295b7e3','eb77ba14-15de-4d4d-aac4-625ebd58b1c6']&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=bea79810-145f-4ad0-a02c-4177a6e7d861&vizid=['fa934657-e347-4de7-b02d-3b46609233cc','62f98ad3-6ddd-4aed-8f13-58054295b7e3','eb77ba14-15de-4d4d-aac4-625ebd58b1c6']&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT

Example response🔗

Each data object returned in the API response contains four components:

  1. The columnNames array that contains a list of all column headers.

  2. The data array that contains a list of sub-arrays. Each sub-array represents a new row of data.

  3. Name of the visualization.

  4. A sampling ratio.

    The sampling ratio tells you the percentage of total data returned. A sampling ratio of 1 indicates that all data in the visualization object was returned in the API response.

Liveboard data🔗

{
  "4fdf9d2c-6f34-4e3b-9fa6-bd0ca69676e1": {
    "name": "Sample Name",
    "columnNames": [
      "Opportunity Stage",
      "Opportunity Owner Name",
      "Total Amount"
    ],
    "data": [
      [
        "s3 alignment with eb",
        "jeff cameron",
        1102272
      ],
      [
        "s4 validation",
        "brian mcquillan",
        59150
      ]
    ],
    "samplingRatio": 1,
    "totalRowCount": 14,
    "rowCount": 14,
    "pageSize": 10,
    "offset": 0
  }
}

Visualization data🔗

The returned JSON data includes one object for every visualization on the Liveboard. If you make a call to obtain data for a specific visualization on a Liveboard, The API returns data for only that visualization.

{
  "fa934657-e347-4de7-b02d-3b46609233cc": {
    "columnNames": [
      "User"
    ],
    "data": [
      [
        9
      ]
    ],
    "samplingRatio": 1,
    "totalRowCount": 1,
    "rowCount": 1,
    "pageSize": -1,
    "offset": -1,
    "name": "MAU Last 30 Days"
  },
  "eb77ba14-15de-4d4d-aac4-625ebd58b1c6": {
    "columnNames": [
      "User",
      "Number of User Action"
    ],
    "data": [
      [
        "tsadmin",
        436
      ],
      [
        "system",
        50
      ],
      [
        "cristi-test",
        8
      ],
      [
        "sandeep2",
        7
      ],
      [
        "sandeep",
        4
      ]
    ],
    "samplingRatio": 1,
    "totalRowCount": 5,
    "rowCount": 5,
    "pageSize": 100000,
    "offset": 0,
    "name": "Top 10 Liveboard Consumers Last 30 days"
  },
  "62f98ad3-6ddd-4aed-8f13-58054295b7e3": {
    "columnNames": [
      "User"
    ],
    "data": [
      [
        2
      ]
    ],
    "samplingRatio": 1,
    "totalRowCount": 1,
    "rowCount": 1,
    "pageSize": -1,
    "offset": -1,
    "name": "Inactive Users"
  }
}

Runtime filters🔗

You can modify the API’s output by passing runtime filters as parameters in the resource URL.

For example:

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=f4533461-caa5-4efa-a189-13815ab86770&batchsize=-1&col1=COL_NAME1&op1=OP_TYPE1&val1=VALUE1&coln=COL_NAMEn&opn=OP_TYPEn&valn=VALUEn

You can add more than one filter by specifying col2, op2, val2, and so on.

ParameterDefinition

col<n>

Name of the column to filter on.

op<n>

{IN, EQ, NE, LT, LE…​}

val<n>

Value of the column to filter on.

Note
 These parameters are case-insensitive. For example, EQ, eq, and eQ have the same result.

Runtime filter operators🔗

OperatorDescriptionNumber of Values

EQ

equals

1

NE

does not equal

1

LT

less than

1

LE

less than or equal to

1

GT

greater than

1

GE

greater than or equal to

1

CONTAINS

contains

1

BEGINS_WITH

begins with

1

ENDS_WITH

ends with

1

BW_INC_MAX

between inclusive of the higher value

2

BW_INC_MIN

between inclusive of the lower value

2

BW_INC

between inclusive

2

BW

between non-inclusive

2

IN

is included in this list of values

multiple

Response codes🔗

HTTP CodeDescription

200

Successful retrieval of Liveboard or visualization data

400

Invalid Liveboard ID