Report APIs

ThoughtSpot provides the following REST API v2 endpoints to download or export data as a file:

POST /api/rest/2.0/report/liveboard
Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format.
POST /api/rest/2.0/report/answer
Download data from a saved Answer, a pinned Answer on a Liveboard, or a Spotter-generated Answer in PDF, PNG, CSV, or XLSX file format.

Note	To retrieve data as JSON instead of downloading a file, see Data APIs.

Liveboard Report API🔗

To download a Liveboard report via /api/rest/2.0/report/liveboard API, you need at least view access to the Liveboard specified in the API request.

In the POST request body, specify the GUID or name of the Liveboard as metadata_identifier. To download reports with specific visualizations, add GUIDs or names of the visualizations in the visualization_identifiers.

To download visualizations from a specific Liveboard tab, specify the name or GUID of the tab in the tab_identifiers parameter.

To download a personalized view of the Liveboard, specify the view name in the personalised_view_identifier attribute.

Important

The downloadable file returned in the Liveboard API response is extensionless. You need to rename the downloaded file by adding the relevant extension. Answer exports are named automatically; see Answer Report API.
If the Liveboard includes Note tiles, ensure that you do not pass the GUID of Note tiles as visualization_identifiers in the API request. Attempting to do so will lead to an error, and the API will return 400 error code in response.
Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error.
If Role-Based Access Control (RBAC) is disabled, DATADOWNLOADING (Can download Data) privilege is required for Liveboard exports.
If the Role-Based Access Control (RBAC) is enabled, the CAN_DOWNLOAD_DETAILED_DATA (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the CAN_DOWNLOAD_VISUALS (Can download visuals) privilege is required for PDF or PNG exports.

File Formats🔗

The default file_format is CSV.

Note	If you do not have .csv downloads enabled for your ThoughtSpot instance, select either `PDF` or `PNG` `file_format` to successfully download the report. Using any other format will cause the API to return an error.

For CSV downloads,

Each visualization is exported as a separate .csv file.
If multiple visualizations are selected, the downloaded report is a single compressed .zip file containing all .CSV files.
It does not support any additional parameters to customize the page orientation and include_cover_page, include_filter_page, logo, footer text, and page numbers.
Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query.

Sample API payload for CSV downloads🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957",
"file_format": "CSV",
"tab_identifiers": [
"bc6d6fb8-1e06-4617-b02f-51745e6933a6"
]
}'

For XLSX downloads,

Visualization is exported as an Excel workbook (.xlsx).
If multiple visualizations are selected, the downloaded report is a single Excel workbook (.xlsx) containing each visualization in their individual tab.
A maximum of 255 tabs per .xlsx workbook are allowed.
It does not support any additional parameters to customize the page orientation and include_cover_page, include_filter_page, logo, footer text, and page numbers.
Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query.
New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity.

Sample API payload for XLSX downloads🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
--data-raw '{
"metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957",
"file_format": "XLSX",
"visualization_identifiers": [
"254c6e30-680c-41ea-aa4d-bb059f745462"
]
}'

For PDF downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers.

You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages.

page_size = CONTINUOUS Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout.

When page_size = CONTINUOUS, the include_filter_page option works to show/hide the filter section in the PDF page (in a continuous PDF, there is no separate filter page, but the filters are included on the same page at the top).
zoom_level offers various download size options to suit the viewer’s screen dimensions, thereby enhancing legibility. This can be set only when page_size = CONTINUOUS. Valid values are integers in the range of 45 and 175.

Sample API payload for PDF downloads🔗

curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957",
  "file_format": "PDF",
  "visualization_identifiers": [
    "254c6e30-680c-41ea-aa4d-bb059f745462"
  ],
  "pdf_options": {
    "page_size": "CONTINUOUS",
    "zoom_level": 105,
    "include_cover_page": true,
    "include_custom_logo": true,
    "include_filter_page": true,
    "include_page_number": true,
    "page_orientation": "PORTRAIT",
    "truncate_table": false,
    "page_footer_text": "Sample footer text"
  }
}'

For PNG downloads, you can now define

image_resolution
image_scale
include_header

Important

If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later,
- You will no longer be able to use the include_cover_page, include_filter_page within the png_options.
- PNG download will support exporting only one tab at a time. If the tab_identifier is not specified, the first tab will be downloaded.
Due to UI limitations in the REST API Playground, you’ll notice that some parameters are automatically included in the PNG options JSON. This may cause your API request to fail. As a workaround, click View JSON next to the png_options, review the parameters, remove additional parameters, and then click Try it out.

Sample API payload for PNG downloads🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957",
  "file_format": "PNG",
  "tab_identifiers": [
    "bc6d6fb8-1e06-4617-b02f-51745e6933a6"
  ],
  "png_options": {
    "include_cover_page": null,
    "include_filter_page": null,
    "personalised_view_id": null,
    "image_resolution": 1920,
    "image_scale": 100,
    "include_header": true
  }
}'

Override filters🔗

If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the override_filters array.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard'  \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  --data-raw '{
  "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125",
  "file_format": "PNG",
  "override_filters": [
    {
      "column_name": "Color",
      "generic_filter": {
        "op": "IN",
        "values": [
          "almond",
          "turquoise"
        ]
      },
      "negate": false
    },
    {
      "column_name": "Commit Date",
      "date_filter": {
        "datePeriod": "HOUR",
        "number": 3,
        "type": "LAST_N_PERIOD",
        "op": "EQ"
      }
    },
    {
      "column_name": "Sales",
      "generic_filter": {
        "op": "BW_INC",
        "values": [
          "100000",
          "70000"
        ]
      },
      "negate": true
    }
  ],
  "png_options": {
    "include_cover_page": true,
    "include_filter_page": true
  }
}'

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 = "http://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/api/rest/2.0/report/liveboard", {
        method: "POST",
        body: createFormDataObjectWith({
            "transient_content": transientPinboardContent,
        }),
    });
 }
< /script>

Answer Report API🔗

To download Answer data via /api/rest/2.0/report/answer API, you need at least view access to the Answer being exported.

The API supports exporting:

Saved Answers
Pinned Answers on a Liveboard
Spotter-generated Answers

You can download Answer data in CSV, XLSX, PNG, and PDF format. The default file_format is CSV.

Important

If Role-Based Access Control (RBAC) is disabled, the DATADOWNLOADING (Can download Data) privilege is required for Answer exports.
If the Role-Based Access Control (RBAC) is enabled, the CAN_DOWNLOAD_DETAILED_DATA (Can download detailed data) privilege is required to export in the PDF, XLSX, or CSV formats, and the CAN_DOWNLOAD_VISUALS (Can download visuals) privilege is required for PNG exports.

Usage guidelines🔗

Use the type and metadata_identifier parameters together to specify the Answer to export. The type parameter distinguishes between a saved Answer and a pinned Answer on a Liveboard. If type is not specified, the API defaults to SAVED.

type metadata_identifier Result Notes

`type`	`metadata_identifier`	Result	Notes
`SAVED` (default)	GUID or name of the saved Answer	Success. Downloads the saved Answer	Omitting `type` produces the same result as setting `type: SAVED`.
`PINNED`	Container ID. represented as `viz_guid` in the TML.	Success. Downloads with Liveboard context. Liveboard-level filters, Runtime Filters, and Column Security Rules (CSR) are automatically applied to the export.	Use container ID (`viz_guid`) as `metadata_identifier`.

SAVED (default)

GUID or name of the saved Answer

Success. Downloads the saved Answer

Omitting type produces the same result as setting type: SAVED.

PINNED

Container ID. represented as viz_guid in the TML.

Success. Downloads with Liveboard context.
Liveboard-level filters, Runtime Filters, and Column Security Rules (CSR) are automatically applied to the export.

Use container ID (viz_guid) as metadata_identifier.

To export a specific Personalized View of a Liveboard, include the personalised_view_identifier parameter with the GUID of that view.

Note	Exported files are automatically named after the Answer title, with the file extension appended based on the selected format. HTML rendering is not supported for PDF exports of Answers with tables.

Find the metadata identifier🔗

For saved Answers (type: SAVED): Send a request to /api/rest/2.0/metadata/search with type: ANSWER to retrieve the Answer GUID.

For pinned Answers (type: PINNED): Use the GUID of the Liveboard that contains the pinned Answer as the metadata_identifier. To find the Liveboard GUID:

In the ThoughtSpot application, open the Liveboard.

Copy the GUID from the address bar.

https://<your-thoughtspot-instance>/#/pinboard/<liveboard-guid>

Alternatively, send a request to /api/rest/2.0/metadata/search with type: LIVEBOARD.

PNG export options🔗

The png_options support the following properties:

Property Type Description

Property	Type	Description
`x_resolution`	Number	Width of the exported PNG in pixels. Valid range: `600px` to `3840px`. Default: `2254px`. This is honored only when neither `x_resolution` nor `y_resolution` is passed. If either value is passed, retaining the default 1.414:1 aspect ratio is prioritized.
`y_resolution`	Number	Height of the exported PNG in pixels. Valid range: `600px` to `3840px`. Default: `1588px`. This is honored only when neither `x_resolution` nor `y_resolution` is passed. If either value is passed, retaining the default 1.414:1 aspect ratio is prioritized.
`scaling`	Integer	Display scale percentage for objects rendered in the image. Adjusts the relative size of visual elements without cropping the image. Valid range: `80%` to `500%`.

x_resolution

Number

Width of the exported PNG in pixels.
Valid range: 600px to 3840px.
Default: 2254px. This is honored only when neither x_resolution nor y_resolution is passed. If either value is passed, retaining the default 1.414:1 aspect ratio is prioritized.

y_resolution

Number

Height of the exported PNG in pixels.
Valid range: 600px to 3840px.
Default: 1588px. This is honored only when neither x_resolution nor y_resolution is passed. If either value is passed, retaining the default 1.414:1 aspect ratio is prioritized.

scaling

Integer

Display scale percentage for objects rendered in the image. Adjusts the relative size of visual elements without cropping the image.
Valid range: 80% to 500%.

Examples🔗

Export a saved Answer (default)🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125",
  "file_format": "PNG"
}'

Omitting type is equivalent to setting "type": "SAVED".

Export a pinned Answer from a Liveboard🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "416052fd-ad22-4d48-be0a-e43b53109957",
  "type": "PINNED",
  "file_format": "CSV"
}'

In this case, metadata_identifier is the GUID of the Liveboard that contains the pinned Answer. Liveboard-level filters, Runtime Filters, and Column Security Rules are automatically applied to the export.

Export a PNG with custom dimensions and scaling🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125",
  "file_format": "PNG",
  "png_options": {
    "x_resolution": 1920,
    "y_resolution": 1080,
    "scaling": 120
  }
}'

Export data generated from Spotter APIs🔗

To export results generated from Spotter APIs such as /api/rest/2.0/ai/answer/create, /api/rest/2.0/ai/agent/converse/sse, and /api/rest/2.0/ai/conversation/{conversation_identifier}/converse, include the session ID and generation number in the POST request body.

When downloading a Spotter-generated Answer, do not specify the metadata object ID, because you will be exporting the data generated from a conversation session with Spotter and not a saved Answer.

Request example🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer'  \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "file_format": "CSV",
  "session_identifier": "ee077665-08e1-4a9d-bfdf-7b2fe0ca5c79",
  "generation_number": 2
}'

session_identifier refers to session ID returned in the Spotter API response.
generation_number indicates the Answer generation number.
file_format specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format.

API Response🔗

If the API request is successful, ThoughtSpot returns the data in the specified file format. You can download the file to use it later or import it into your application environment.

Pagination and runtime overrides🔗

The Report API endpoints support the same runtime overrides as the Data API endpoints. For more information, see Runtime overrides.

For information about pagination, record size, and the maximum row limit that apply to the Data API endpoints, see Pagination settings for Data APIs.