Pinboard data API

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

Using this API, you can fetch the following information:

  • All the visualization objects on a pinboard

  • A specific or a group of visualizations on a pinboard

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

Request URL

POST /tspublic/v1/pinboarddata

Request parameters

Query parameter Description

id

String. GUID of pinboard.

vizid Optional

String. A JSON array of GUIDs of the visualizations.

batchsize

Integer. The batch size for loading pinboard 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 pinboard 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.

Example requests

Pinboard data

CURL
curl -X POST \
--header 'Content-Type: application/json' \
--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/json' \
--header 'Accept: application/json' \
--header 'X-Requested-By: ThoughtSpot' \ 'https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/pinboarddata?id=bea79810-145f-4ad0-a02c-4177a6e7d861&vizid=%5B'fa934657-e347-4de7-b02d-3b46609233cc'%2C'62f98ad3-6ddd-4aed-8f13-58054295b7e3'%2C'eb77ba14-15de-4d4d-aac4-625ebd58b1c6'%5D&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

https://<ThoughtSpot-host>/callosum/v1/tspublic/v1/pinboarddata?id=bea79810-145f-4ad0-a02c-4177a6e7d861&vizid=%5B'fa934657-e347-4de7-b02d-3b46609233cc'%2C'62f98ad3-6ddd-4aed-8f13-58054295b7e3'%2C'eb77ba14-15de-4d4d-aac4-625ebd58b1c6'%5D&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.

Pinboard 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 pinboard. If you make a call to obtain data for a specific visualization on a pinboard, 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 Pinboard 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.

Parameter Definition

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.

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

Runtime filter operators

Operator Description Number 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 status code Description

200

Successful retrieval of pinboard or visualization data

400

Invalid pinboard ID