# Report APIs > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/report-apis # 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`](#_liveboard_report_api) Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. - [`POST /api/rest/2.0/report/answer`](#_answer_report_api) 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 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 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 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 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. ```JSON 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. ```JavaScript function getExportRequestForCurrentPinboard(frame: HTMLIframeElement): Promise; ``` 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 ```JavaScript < 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> ``` See also, [HostEvent.getExportRequestForCurrentPinboard](https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard). ## 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 | | --- | --- | --- | --- | | `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: 1. In the ThoughtSpot application, open the Liveboard. 2. Copy the GUID from the address bar. https:///#/pinboard/ 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 | | --- | --- | --- | | `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 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 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 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 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]({{navprefix}}/{{data-apis-v2}}#_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]({{navprefix}}/{{data-apis-v2}}#pagination).