Embedding ThoughtSpot, explained.

Rules 2 and 4 are one-sided security rules the docs state. Rules 6 to 8 are SDK mechanics explained in their sections. Rules 1, 3, 5, 9 and 10 are our guidance, with the alternatives in the linked section.

Sources for this table: docs docs docs docs.

Deprecated classes you may still see

This table is our synthesis of the documented selection guidance, not a table the docs publish; cells marked as inference are ours. Per-Org IdPs and a Per Org Subdomain exist for clusters that use Orgs. docs docs

Facts are from the docs; the trade-offs are our reading. Where the docs are silent we say so.

import express from 'express';

const app = express();
const TS_HOST = process.env.TS_HOST;            // https://your-instance.thoughtspot.cloud
const SECRET_KEY = process.env.TS_SECRET_KEY;   // from your secrets manager, never sent to the browser

// 1. requireAppSession rejects unauthenticated requests (401).
app.get('/ts-token', requireAppSession, async (req, res) => {
  // 2. Identity comes from YOUR verified session, not from req.query or req.body.
  const username = req.user.email;

  const tenant = await lookupTenant(req.user);   // your data: org, groups, RLS values

  const r = await fetch(`${TS_HOST}/api/rest/2.0/auth/token/custom`, {
    method: 'POST',
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'X-Requested-By': 'ThoughtSpot',
    },
    body: JSON.stringify({
      username,
      secret_key: SECRET_KEY,
      validity_time_in_sec: 300,           // the default; a security trade-off, see the lifetime notes
      org_identifier: tenant.org,          // only if Orgs are enabled
      persist_option: 'REPLACE',           // required; APPEND or REPLACE when sending variable_values
      // JIT: create the user on first visit (existing users are not updated)
      auto_create: true,
      display_name: req.user.name,
      email: req.user.email,
      groups: [{ identifier: tenant.group }],
      // ABAC: values for the formula variable your RLS rule reads
      variable_values: [{ name: 'allowed_regions', values: tenant.regions }],
    }),
  });

  if (!r.ok) {
    console.error('token mint failed', r.status); // 6. audit log, no secrets
    return res.status(502).json({ error: 'token_unavailable' });
  }
  const { token } = await r.json();
  res.set('Cache-Control', 'no-store');
  res.json({ token });
});

The fields follow the auth/token/custom reference. docs allowed_regions and lookupTenant are placeholders for your own names.

import { init, AuthType } from '@thoughtspot/visual-embed-sdk';

init({
  thoughtSpotHost: 'https://your-instance.thoughtspot.cloud',
  authType: AuthType.TrustedAuthTokenCookieless,
  autoLogin: true,
  getAuthToken: () =>
    fetch('/ts-token', { credentials: 'include' })
      .then((r) => r.json())
      .then((d) => d.token),
});

No RLS variables and no JIT? auth/token/full with username, secret_key and validity_time_in_sec is enough, and its auto_create defaults to false. docs

These are review guidance from experience. The linked docs cover the underlying facts.

Documented facts, then options with trade-offs. The options are our guidance.

• EmbeddedSSO behaves like None if SSO is not configured on the cluster.
• TrustedAuthToken: the docs list it for an IdP that does not support Embedded SSO, users who do not exist in your IdP, or multiple IdPs without federation. It works in most situations only with ThoughtSpot on the same top-level domain as the app (custom domain); cookieless avoids the same-domain constraint.
• SAMLRedirect and OIDCRedirect need SAML redirect domains allowlisted in Security Settings.
• None needs partitioned cookies enabled in dev and test.
• To avoid reloading the host in redirect flows, use popup mode: inPopup: true (SDK 1.18.0) with authTriggerContainer and authTriggerText, or useEventForSAMLPopup and authEE.emit(AuthEvent.TRIGGER_SSO_POPUP). The noRedirect option is deprecated; use inPopup. Deprecated docs

• With cookieless auth the SDK uses the token as a bearer token and establishes no session, so a plain fetch() to /api/rest/2.0/... carries no credential. The REST page says to obtain a bearer token or set session cookies before calling an endpoint. docs That a bare fetch() then fails is our inference from those two statements.
• tokenizedFetch takes the same arguments as the Web fetch and adds the token to the request. The docs say it works for any authorization method. docs
• The docs' own example stores the token in a global variable from inside getAuthToken for other REST calls. docs A token never extends, and autoLogin replaces it before expiry, so a saved copy goes stale (our inference). tokenizedFetch avoids keeping one.
• Returning a reused token from getAuthToken triggers DUPLICATE_TOKEN_ERR, so do not point getAuthToken at a cached copy to share it. docs

import { tokenizedFetch } from '@thoughtspot/visual-embed-sdk';

const r = await tokenizedFetch(`${TS_HOST}/api/rest/2.0/auth/session/user`, {
  method: 'GET',
  headers: { Accept: 'application/json' },
});
if (!r.ok) throw new Error(`REST ${r.status}`);

If cookies are blocked in cookie-based mode, the SDK emits EmbedEvent.NoCookieAccess and you should switch to cookieless. Because the token is used once, the docs suggest a validity under a minute. docs

• autoLogin: true makes the SDK request a new token before the current one or the session expires, so the user never sees a signed-out embed. docs
• refreshAuthTokenOnNearExpiry is a view config option (documented on AppViewConfig, SearchViewConfig and the conversation view configs) and defaults to true. New SDK 1.45.2+ · TS 26.3.0.cl+ docs
• Revoking on sign-out matters more the longer your cookieless tokens live. The revoke endpoint (9.0.0.cl+) takes a user_identifier or a token; revoking another user's token needs sufficient privileges per the REST reference. docs

Which token endpoint (reference)

Multi-Org tokens Beta A token request by a cluster administrator can carry a scope object instead of org_id, and each API call then picks its Org with the X-Org-Selector header. full, object and custom support it, and custom supports SPECIFIC_ORGS only. It is disabled by default and needs Support to enable. docs Our guidance: treat it as an admin or back-office tool, not a replacement for one token per tenant user.

EmbedEvent.AuthFailure, EmbedEvent.IdleSessionTimeout and EmbedEvent.AuthLogout appear in the docs error table but are not listed in the EmbedEvent enum reference, so confirm them in your SDK version; the AuthStatus signals on the init() emitter are the ones the enum reference documents. docs

import { AuthStatus, AuthFailureType } from '@thoughtspot/visual-embed-sdk';

authEE.on(AuthStatus.SDK_SUCCESS, () => renderEmbed());          // token exchange done
authEE.on(AuthStatus.SUCCESS, (s) => console.log(s.userGUID));   // iframe confirmed
authEE.on(AuthStatus.FAILURE, (type) => {
  // type is an AuthFailureType: EXPIRY | IDLE_SESSION_TIMEOUT | NO_COOKIE_ACCESS
  //   | OTHER | SDK | UNAUTHENTICATED_FAILURE
  if (type === AuthFailureType.NO_COOKIE_ACCESS) fallBackToCookieless();
});
authEE.on(AuthStatus.LOGOUT, () => goToAppSignIn());

Other relevant options on init(): disableLoginRedirect (SDK 1.9.3, pair with token auth plus autoLogin), loginFailedMessage, disableLoginFailurePage (SDK 1.32.3) and, for full-app embeds, blockNonEmbedFullAppAccess (SDK 1.22.0), which blocks users from opening ThoughtSpot pages outside the iframe. docs

The docs note that many ThoughtSpot features are tied to individual user accounts with a valid email address, and that JIT provisioning and the user REST APIs make creating them easy. Shared customer-level or role-level accounts are possible, but the docs say to discuss them with your ThoughtSpot team because of access-control and RLS implications. The per-user preference below is our reasoning from that, not a docs rule. docs

The effect happens at token creation, not at use. You need display_name and email, plus org_id when Orgs are enabled, and group_identifiers only if you want JIT group assignment. The token request needs secret_key, because the username and password path cannot JIT. Creating users requires administration privilege (or CONTROL_TRUSTED_AUTH under RBAC). docs

Sources: the JIT page and the REST v2 authentication guide. docs docs

• POST /api/rest/2.0/users/create (9.0.0.cl+): requires name, display_name, email. Optional account_type (LOCAL_USER, LDAP_USER, SAML_USER, OIDC_USER, REMOTE_USER), org_identifiers, group_identifiers, account_status, visibility, preferred_locale. docs
• POST /api/rest/2.0/users/import (9.0.0.cl+): bulk upsert and sync. dry_run defaults to true, so nothing is written until you set it false. delete_unspecified_users defaults to false and is destructive when true (it never deletes tsadmin, guest, system or su). docs

Explicit provisioning gives you full control of every option and does not couple user changes to token minting. A common pattern is explicit sync for groups and roles (a scheduled import) plus auto_create only as a safety net for first login. The token service needs secret_key and a separate admin service account for any other REST calls; do not confuse the two. docs

There is one non-deletable Primary Org with ID 0. Orgs require an Analytics Enterprise or ThoughtSpot Embedded license, are enabled by default on new Enterprise cloud instances, and cannot be turned off once enabled. docs docs

• Scope a token to an Org with org_id (full, object) or org_identifier (custom). If omitted with a secret_key, the token is for the Org that key belongs to. docs
• Per-Org secret keys exist from 9.2.0.cl, enabled by contacting Support. You can also enable trusted auth programmatically with POST /api/rest/2.0/auth/configure (26.6.0.cl or later). docs docs
• Create Orgs with POST /api/rest/2.0/orgs/create (9.0.0.cl+; cluster admin, or ORG_ADMINISTRATION under RBAC). docs
• Per-Org SSO: with a per-Org IdP, only claims referencing that IdP's Org are honored; cross-Org claims are dropped and logged as security audit events, and existing manually assigned Org memberships are not removed by a per-Org IdP login. docs Separately, OIDC Org mapping needs Support to enable; while it is on, group mapping does not work, and a mapped login assigns the user only to the Orgs in the assertion (removing the others). docs
• Per Org Subdomain (<org>.<cluster>.thoughtspot.cloud) is generally available (it was Early Access before 26.5.0.cl) and is enabled by contacting Support. Org names must be DNS-friendly and new Orgs need a new request. GA docs
• Per-Org custom embed URL and cross-Org links (overrideOrgId, SDK 1.35.0) are generally available since 26.5.0.cl (Early Access from 10.5.0.cl before that) and enabled via Support; the docs note overrideOrgId may not work with trusted auth if tokenAuthPerOrg is enabled. GA docs

Orgs versus one Org, in trade-offs

Facts are from the Orgs and rate-limit pages. docs docs Cost and effort cells are our judgement.

Single Org with data-level separation

One Org with a tenant_id column and RLS or ABAC on top. All tenants share one set of data objects. It is lighter to operate for many small tenants, but isolation depends entirely on correct rules and tokens. docs Runtime filters and Liveboard filters are not a security boundary; use RLS or ABAC for anything where a wrong answer is a data leak. docs

Documented behaviour first; the sequencing is our guidance. We found no SCIM provisioning described in the embedding docs.

Role-based access control replaces group-level privileges with roles, which are collections of privileges such as manage users, groups, roles, Orgs, authentication or application. It is off by default, you enable it by contacting Support, and once enabled it cannot be disabled. Existing group privileges migrate to role privileges. docs

• Privilege names change under RBAC: creating users needs USER_ADMINISTRATION, token auto_create needs CONTROL_TRUSTED_AUTH, managing formula variables for custom tokens needs CAN_MANAGE_VARIABLES, and orgs/create needs ORG_ADMINISTRATION. docs docs
• Role endpoints: roles/search, roles/create, roles/{role_identifier}/update, roles/{role_identifier}/delete, from 9.5.0.cl. docs
• Your token service and admin service account need the right RBAC privileges, or JIT and provisioning calls start failing after enablement.

The docs describe each mechanism but do not rank them. Cells marked docs restate a documented behaviour. Cells marked our reading are our judgement, and where the docs are silent the cell says so. docs docs

What tips the choice. Who already holds warehouse accounts. Whether entitlements change per login or per week. Whether you can run a token service. Whether your auditors want enforcement in the warehouse or in ThoughtSpot. Combinations are common: a tenant group rule plus an ABAC variable for a sub-tenant attribute is described in the docs as a layering, not an either-or. docs

Testing tenant isolation

Docs: log in as a user without the bypass privilege, start the session with the ABAC token, open a Liveboard, Saved Answer or new search, inspect the generated SQL, confirm only permitted rows show, confirm no data shows when no values are set, and repeat for different assignments. docs Our guidance, not in the docs: add negative tests where tenant A asks for tenant B's values through filters, Spotter and downloads, and run them again after every model or rule change.

Include Spotter in the test matrix: the docs state it runs through the instance, which enforces RLS and CLS. Exports and schedules are our addition to the matrix, because the docs we checked do not test them for you.

The lifecycle in three calls

// POST /api/rest/2.0/template/variables/create
{ "type": "FORMULA_VARIABLE", "name": "region_var", "is_sensitive": false, "data_type": "VARCHAR" }

Types are VARCHAR, INT32, INT64, DOUBLE, DATE and DATE_TIME. BOOLEAN and TIME are not supported. Creating variables needs a cluster or Org admin, or the CAN_MANAGE_VARIABLES privilege. docs The 10.9.0.cl REST changelog tagged the template/variables endpoints Beta; the ABAC guide does not restate that, so check current status for your release. docs

region = ts_var(region_var)

No quotes around the variable name. Add rules for each variable the table needs. docs

// POST /api/rest/2.0/auth/token/custom
{ "username": "UserA",
  "secret_key": "<from your secret store>",
  "validity_time_in_sec": 300,
  "persist_option": "REPLACE",
  "variable_values": [
    { "name": "region_var", "values": ["NA", "EMEA"] }
  ],
  "objects": [ { "type": "LOGICAL_TABLE", "identifier": "<model-guid>" } ] }

Rules that matter

Deprecated See the paragraph below for the conflicting docs and the plan to move off.

Before formula variables, tokens carried filter_rules and parameter_values that bound to column and parameter names. The docs conflict on its status. The ABAC page marks the approach Deprecated in 26.3.0.cl, "will be removed in a future release", with existing implementations continuing "until further notice". docs The REST changelog is narrower: for 26.3.0.cl filter_rules is no longer available for new configurations, while parameter_values is supported and "will be deprecated in an upcoming version"; What's new also does not call parameter_values deprecated yet. docs user_parameters on /auth/token/full and /object has been deprecated since 10.4.0.cl. The safe position: no new work on any of them, and plan for all to go. No removal date is stated. Use ABAC via RLS for all new work. docs An older Beta flow through /auth/token/full and /auth/token/object is also deprecated, with its own migration guide. docs

Cutover plan

1. Audit. List every place your backend sends filter_rules or parameter_values, and which columns and Models they touch. Follow the official migration guide. docs
2. Create variables for each attribute (variables/create, then reference them in rules).
3. Add RLS rules with ts_var() on the Tables. Legacy filters and RLS both apply, so the result is the intersection and can only be stricter. Field-observed
4. Send both for a coexistence window: legacy fields plus variable_values. Verify with a non-admin user and POST /api/rest/2.0/template/variables/search using response_content: METADATA_AND_VALUES, and inspect the generated SQL. docs
5. Remove the legacy keys from the mint request. Avoid sending an empty values: [] to clear things unless you intend a wipe. Standardize on one mint endpoint. Field-observed

Spotter, the Spotter MCP server and the Spotter REST APIs all run through the ThoughtSpot instance, which "enforces data security with RLS and CLS rules". Your existing models and governance carry over. docs docs

• runtimeFilters on SpotterEmbed (SDK 1.41.0 / TS 10.13.0.cl) persist across a conversation, but remain context, not security. docs
• CAN_USE_SPOTTER gates access to Spotter. CAN_MANAGE_SPOTTER does not override data access permissions. docs
• The docs returned for this guide do not describe how Spotter's language-model prompts treat sample values beyond the statement above. Our guidance: keep sensitive columns covered by RLS or CLS, and weigh disabling indexing on them.

Firm rules (doc-stated, or the risk is one-sided):

Judgement calls, covered above: which pattern, APPEND or REPLACE, and Org per customer or shared Org.

These are set under Develop > Customizations > Security settings, or with POST /api/rest/2.0/system/security-settings/configure. They need an embedding license. Some are cluster-level only and some can be overridden per Org. docs The REST reference tags the endpoint TS 26.2.0.cl+ and requires the ADMINISTRATION or DEVELOPER privilege (cluster-level SAML and script-src settings need ADMINISTRATION). docs

Sources: CSP domain formats per-Org SAML non-embed selective access. Mobile and hybrid apps can use custom schemes such as capacitor://localhost in the lists, but a shared scheme does not identify your app: every app on the device using that framework presents the same origin, so it is not an access-control boundary and you must enforce access with cookieless trusted auth. docs

// POST /api/rest/2.0/system/security-settings/configure
{ "cluster_preferences": {
    "csp_settings": { "visual_embed_hosts": ["app.example.com"] },
    "non_embed_access": { "block_full_app_access": false } },
  "org_preferences": [ { "org_identifier": "<org-name-or-id>",
      "non_embed_access": {
      "block_full_app_access": true,
      "groups_identifiers_with_access": ["group1"] } } ] }

On the SDK side, blockNonEmbedFullAppAccess exists in init() (SDK 1.22.0+ · TS 9.3.0.cl+). The reference lists a default of true but also marks the option Optional, so set it explicitly if you rely on it. docs From 10.6.0.cl the docs treat the Security Settings toggle and selective user access as the control; they say selective access overrides the SDK flag and that "support for the SDK blockNonEmbedFullAppAccess will end soon". Options: (a) the server-side setting, which the docs treat as the control and which is not tied to an SDK version, at the cost of a per-Org setting to review; (b) the SDK flag, which needs no cluster change but whose support the docs say will end soon. Our reading: do not build new work only on the SDK flag. docs

Embeds expose menu actions (download, share, schedule, edit and so on). You can shape them with visibleActions (allowlist; an empty array removes all), hiddenActions (denylist), and disabledActions (greyed out but visible) with disabledActionReason as the hover tooltip. Setting both visibleActions and hiddenActions leads to an error in the embedded content. docs Action IDs come from the Action enum, and which ones apply depends on the embed type, so try them in the Visual Embed Playground before shipping. Custom actions get an automatic ID you can use in the same arrays. docs docs

const embed = new LiveboardEmbed('#tsEmbed', {
  liveboardId: '<guid>',
  visibleActions: [Action.Save, Action.Pin, Action.DownloadAsPdf], // never combine with hiddenActions
  disabledActions: [Action.Download],
  disabledActionReason: 'Download is restricted for your role. Contact your administrator',
});

Granular download privileges replace the legacy DATADOWNLOADING ("Can download Data"): when enabled, that privilege ceases to exist, previous holders receive both new ones, and non-holders receive neither. With granular RBAC on, the Answer Report API requires CAN_DOWNLOAD_DETAILED_DATA for PDF, XLSX and CSV and CAN_DOWNLOAD_VISUALS for PNG, while the Liveboard Report API requires CAN_DOWNLOAD_DETAILED_DATA for XLSX and CSV and CAN_DOWNLOAD_VISUALS for PDF and PNG. The data APIs (searchdata, Liveboard and Answer data) need DATADOWNLOADING, or CAN_DOWNLOAD_DETAILED_DATA when granular privileges are on. docs docs docs GA The RBAC page still labels both privileges Early Access, "not enabled by default", and says to contact ThoughtSpot Support to enable them, while What's New (August 2026) says they are generally available for RBAC-enabled clusters and the 26.8.0.cl REST changelog lists them for the roles endpoints. The docs conflict; confirm on your cluster. docs docs

For AppEmbed navigation, the V3 (HomePage.ModularWithStylingChanges) and V4 (HomePage.Focused, with PrimaryNavbarVersion.Sliding) home experiences offer showPrimaryNavbar, hideApplicationSwitcher, disableProfileAndHelp, hideOrgSwitcher, hideNotification, hideObjectSearch and hideHamburger. These are also UI-level. docs

• Token side effects such as auto_create and persisted values happen when a token is created, not used. Do not pre-generate tokens you may discard. docs
• Just-in-time creation (auto_create): on saves provisioning work and lets a token request create users, off keeps creation under your control. Auto-created groups are created with default options (the docs; field reports say with no privileges Field-observed), and /token/custom sets groups only at creation. docs
• You can revoke tokens on sign-out with POST /api/rest/2.0/auth/token/revoke. docs
• Orgs can have their own secret key (9.2.0.cl+; contact ThoughtSpot Support to enable). A token request made with a per-Org key logs the user into the Org tied to that key. docs docs

Items below are context-dependent. The docs give the mechanism, and the rest is our reading, labelled.

Privileges worth governing

Our guidance: keep these off embed end users, keep holder lists short, and check them on a schedule against the audit log. The secret key rotation cadence is not described in the docs we checked, so set it from your own policy.

Firm rules (doc-stated or one-sided risk): treat hidden actions as UX and enforce with privileges; review security settings for each Org after creating it, because CORS and non-embed blocking can differ per Org; never call the token API from front-end code; never put catch-all hosts such as https://*.com in CSP or CORS; do not assume hiding Download blocks the Report API.

Anything you send before the iframe is ready can be dropped or race with loading. This is the safe order.

import { init, LiveboardEmbed, EmbedEvent, HostEvent, AuthType } from '@thoughtspot/visual-embed-sdk';

// 1. Once per page load.
const auth = init({ thoughtSpotHost, authType: AuthType.TrustedAuthTokenCookieless, getAuthToken });

// 2. Per embed: create, subscribe, render.
const embed = new LiveboardEmbed('#container', { liveboardId });
embed.on(EmbedEvent.Error, (e) => {
  // Payload shapes differ by source: { error }, { code, message }, { offlineWarning },
  // or a typed filter error. Read defensively, log, then decide per category.
  const p = e?.data ?? e;
  logEmbedError({ embed: 'sales-board', code: p?.code, errorType: p?.errorType,
                  severity: p?.severity, message: p?.message ?? p?.error ?? p?.offlineWarning });
});
// Documented per-event form: fires when that host event's listener is registered.
embed.on(`${HostEvent.GetFilters} Subscribed`, async () => {
  // 3. Safe to send this host event now.
  const filters = await embed.trigger(HostEvent.GetFilters);
});
await embed.render();

// 4. Before re-rendering into the same container, or on unmount:
embed.destroy();

The docs’ own handler reads payload.error, payload.code and payload.offlineWarning directly, while the events page shows { type, data: { errorType, error } }, so the sketch above reads both. logEmbedError is your function. docs docs

The v2 framework adds stricter payload validation and context-aware routing. The deprecation notice says the default behavior of host events will be replaced by the v2 framework in 26.10.0.cl. The docs conflict on this: the routing page still calls v2 beta and disabled by default, and the migration guide has you enable it with useHostEventsV2: true (it no longer carries a Beta label, and says migrating does not introduce breaking changes). docs

1. Inventory every embed.trigger(HostEvent.*) call in your code, including ones in shared wrappers.
2. In dev and staging only, set useHostEventsV2: true in the embed’s view config (for example the options you pass to new LiveboardEmbed()); it is not an init() option. SDK 1.45.2+ · TS 26.3.0.cl+ docs
3. Run your flows and watch EmbedEvent.Error for payload validation failures (code HOST_EVENT_VALIDATION). v2 validates payloads strictly. docs
4. Check each event against the current context. A host event aimed at the wrong layer returns a context error instead of acting. Read the context with getCurrentContext() and pass a ContextType as the third trigger() argument where needed. docs
5. Fix payloads and ship the fixes. Then choose your production timing (options below).

Never set shouldBypassPayloadValidation: true in production. docs These steps are our summary of the migration guidance; follow the linked guide for the authoritative checklist.

When to turn v2 on in production: options

The docs ask you to try v2 in a non-production environment first. Production timing is not prescribed, and the docs contradict each other on v2’s status, so these are our reading of the trade-offs.

Our guidance: run v2 in dev and staging in either case, as the docs advise. Confirm on your own cluster which framework is active before relying on either row. docs docs

Host Events V2 and context routing

The v2 framework routes each host event to the layer that is currently active (a Liveboard, an Answer, Spotter, and so on). Only one layer handles an event. If you aim at the wrong layer you get a context error rather than an action on the wrong object. You can read the context but not set or inject it, and only the top-most layer is active. docs

Beta The routing page still describes v2 as beta and disabled by default (its text has not been updated for 26.10.0.cl), and the migration guide no longer labels it Beta but still has you enable it with useHostEventsV2, while the deprecation notice says v1 is deprecated at 26.10.0.cl and its default behavior will be replaced by v2. The docs conflict and do not reconcile the two. Treat v2 as opt-in until you confirm the behavior on your cluster, and test it now. docs docs

// useHostEventsV2 is a view-config option on the embed, not an init() option.
const embed = new LiveboardEmbed('#container', { liveboardId, useHostEventsV2: true });
await embed.render();

const ctx = await embed.getCurrentContext();   // Promise of a ContextObject
if (ctx?.currentContext?.name === 'spotter') {
  // act on the Spotter layer
}
await embed.trigger(HostEvent.Pin, payload, ContextType.Answer);

ContextType members: Answer, Liveboard, Other, Search, Spotter (SDK 1.45.2 | TS 26.3.0.cl). docs

Sources: EmbedEvent HostEvent load events. HostEvent.DestroyEmbed is SDK 1.41.0 | TS 10.12.0.cl; EmbedConfig.waitForCleanupOnDestroy makes destroy() wait for it. docs

Source: error-handling guidelines. The page treats all other error categories (filters, fullscreen, API) as log-and-inspect. Structured enums ErrorDetailsTypes, EmbedErrorCodes, and the EmbedErrorDetailsEvent type arrived in SDK 1.45.0. docs

Observability: what to log

EmbedEvent.Error is per embed component and is not cached or replayed, so a handler registered after the error never sees it. docs The docs say to log errors for diagnostics and not to show raw error objects or stack traces to users. docs

Correlation. The docs do not define a correlation id. A common approach (our guidance, not doc-stated) is to tag every log line with your own embed name, the object id, your app user or session id, the SDK version, and the cluster release, so an embed error can be matched to your backend token-mint log. Check your privacy policy before logging userGuid or message text.

Testing. The docs suggest simulating failures such as network loss and invalid filters, and enabling useHostEventsV2: true in development or staging. docs The Visual Embed Playground lets you try events and preview changes. docs How many non-production clusters or Orgs you run is your call. For moving content between them, the Git integration docs say to use one branch per Org and one repository per project. docs

SDK version pinning and upgrades

ThoughtSpot ships a new SDK version with each major cloud release and tells you to use the recommended version. Every symbol carries two minimums, the SDK and the cluster. docs

Source: What’s new. Use the row for your cluster; newer SDK features may not exist on an older cluster.

The docs state that you should always use the recommended SDK version and review the changelog for breaking and deprecated items. docs How you get that version into your page is a trade-off.

Upgrade cadence has the same shape. Following each cloud release keeps you on the table’s recommended row and means a regression run every cycle. Lagging a release saves test cycles but you may miss fixes, and the docs reviewed do not state whether an older SDK is supported on a newer cluster. Our guidance: stage every bump against a non-production cluster first. Do not assume a 26.10 or 26.11 feature exists on your cluster because the reference lists it; every symbol carries both minimums.

Deprecated names keep working for a short period, so the timing is yours, but each has a stated end of support. Examples: AuthType.SSO (deprecated in SDK 1.13.0; use AuthType.SAMLRedirect), searchQuery to searchOptions, isLiveboardStylingAndGrouping to isLiveboardMasterpiecesEnabled. docs docs

All three options below sit on the same lifecycle. They differ in who owns create, subscribe, render and destroy.

Several embeds on one page. The docs suggest putting several visualizations on one Liveboard and embedding that, rather than many embeds. docs If you do need several, each embed registers its own EmbedEvent.Error handler, and queueMultiRenders: true (default false) starts each render after the previous one finishes, trading total load time for lower browser load. docs

Pre-render. The docs compare five loading strategies. docs

A pre-rendered embed is reused only if the real embed’s config matches, and pre-rendered iframes are attached to the page body unless you set preRenderConfig.containerSelector. docs More detail is in the Performance section.

A single Liveboard can be narrowed by several independent mechanisms at once. The docs describe a wider stack of layers (row-level security, Model filters, runtime filters and parameters, Liveboard filters, cross filters, search query filters) docs. Each has its own API and its own visibility to the user.

Observed on ThoughtSpot 26.8.0.cl with SDK 1.49.0 Field-observed: it works per column. A column you send is replaced with the new values. A column you omit is left alone. A column sent with values: [] is cleared; the docs also show clearing a runtime filter this way docs. Sending an empty array of filters changes nothing. The docs say filters are "appended" but do not spell out the per-column replace rule or the empty-array no-op, so treat those as observed and re-test after upgrades.

The docs also state the event resets the object to its original state, so user changes such as drills are cleared. It is supported in LiveboardEmbed and AppEmbed docs.

A runtime filter is { columnName, operator, values }. If a Model column has an alias, use the base column name docs. The members of RuntimeFilterOp docs docs:

The range operators take two values; EQ and LE take one, and IN takes a list docs. The bound semantics above come from the enum definitions. Still test range filters on your cluster, especially on date columns.

The docs say DATE and DATE_TIME runtime-filter values must be given as epoch time: seconds since 1 Jan 1970 00:00:00 UTC docs. Send them as numbers, computed in UTC. A string epoch being silently ignored, and local midnight landing on the wrong day for anyone not in UTC, are what we observed Field-observed.

// 'YYYY-MM-DD' from a date input -> epoch SECONDS at 00:00 UTC, as a Number
function utcEpoch(ymd) {
  const [y, m, d] = ymd.split('-').map(Number);
  return Date.UTC(y, m - 1, d) / 1000;        // not new Date(ymd).getTime()
}

// inclusive range, end of day included
const start = utcEpoch('2026-01-01');
const end   = utcEpoch('2026-01-31') + 86399;

liveboardEmbed.trigger(HostEvent.UpdateRuntimeFilters, [{
  columnName: 'Order Date',
  operator: RuntimeFilterOp.BW_INC,
  values: [start, end],                       // numbers, never strings
}]);

If you keep filter state as strings (in a form or a URL), convert at the moment you trigger, not when you store.

Because the event appends per column, "send what changed" leaks stale columns. A column the user removed in your UI stays applied in ThoughtSpot until you clear it. Keep one source of truth in your app, and on every change push the whole desired set plus clears for anything that was applied before and is now gone.

let applied = new Set();                      // columns currently applied in the embed

function pushRuntimeFilters(embed, desired) { // desired: [{ columnName, operator, values }]
  const wanted = new Set(desired.map(f => f.columnName));
  const clears = [...applied]
    .filter(col => !wanted.has(col))
    .map(columnName => ({ columnName, operator: RuntimeFilterOp.EQ, values: [] }));

  embed.trigger(HostEvent.UpdateRuntimeFilters, [...desired, ...clears]);
  applied = wanted;
}

// Re-render: runtimeFilters in the config start from scratch, so reset the tracker.
function onRerender() { applied = new Set(); }

Two more rules. Always call embed.destroy() before re-rendering, and reset your tracker when you do. And because the event also resets the object to its original state, any drill the user made is cleared on every push docs.

• The runtime filters operation returns an error if the URL exceeds 2000 characters docs. Since SDK 1.45.0 runtime filters are no longer in the iframe URL by default; the excludeRuntimeFiltersfromURL flag controls it docs.
• Overriding existing filter values with runtime filters while exporting a Liveboard errors docs.
• Limits differ by path. URL-based runtime filters are capped at exactly 50 and the cap cannot be configured. Runtime filters passed through the SDK runtimeFilters property have a configurable limit whose default and maximum is 1,000 (contact ThoughtSpot Support to change it). Filters past either limit are dropped silently, with no error, warning, or event docs. Count them before you push, and log the count on your side, because nothing else will tell you (our guidance).
• Filter failures that do happen surface through EmbedEvent.Error with typed errors such as NON_EXIST_FILTER, INVALID_DATE_VALUE and INVALID_OPERATOR, and invalid host-event payloads through codes such as UPDATEFILTERS_INVALID_PAYLOAD. Log them with the filter you sent, as in the lifecycle observability table. docs docs
• On UpdateFilters, an empty values array removes the values but leaves the chip, and clearing date filters this way is not supported docs.
• In Spotter, runtime filters keep applying to all answers in the same conversation session unless explicitly overridden. SDK 1.41.0 · TS 10.13.0.cl+ docs
• Parameters: once a parameter chip is hidden through runtimeParameters, a URL override, or isVisibleToUser: false, it stays hidden for the embed's lifetime unless you create a new embed object docs. In Spotter, parameter values cannot change mid-conversation docs. SDK 1.25.0 · TS 9.2.0.cl+ (UpdateParameters: SDK 1.29.0 · TS 10.1.0.cl)
• UpdateFilters uses date types such as EXACT_DATE, EXACT_DATE_RANGE, LAST_N_PERIOD, with YYYY-MM-DD or YYYY/MM/DD strings, or numeric epochs (numbers, not strings) docs. SDK 1.23.0 · TS 9.4.0.cl+

// 1. Runtime filter at init: host-imposed context
new LiveboardEmbed(el, { liveboardId, runtimeFilters: [
  { columnName: 'Region', operator: RuntimeFilterOp.IN, values: ['West'] } ] });

// 2. Runtime parameter
liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ name: 'Discount', value: 10 }]);

// 3. Visible Liveboard filter chip the user can edit
liveboardEmbed.trigger(HostEvent.UpdateFilters, { filter:
  { column: 'Region', oper: 'IN', values: ['East'] } });

// Read what is applied (resolves with data, not via callback)
const current = await liveboardEmbed.trigger(HostEvent.GetFilters);

Items marked (our guidance) are judgement, not doc-stated. The rest follow the cited docs.

• Code-based custom actions need SDK 1.43.0+ docs. TS 10.14.0.cl introduced them docs.
• position: CustomActionsPosition.CONTEXTMENU is valid for VIZ, ANSWER and SPOTTER, not LIVEBOARD docs.
• Read the action id with payload?.id ?? payload?.data?.id: classic Liveboards use payload.id, the new experience payload.data.id docs.

/** The clicked point, for a left-click and for a context-menu action. */
function clickedPoint(payload) {
  const d = payload?.data ?? payload ?? {};
  const cmp = d.contextMenuPoints;
  return d.clickedPoint
    ?? (Array.isArray(cmp) ? cmp[0] : cmp?.clickedPoint)   // object on tables, array on some surfaces
    ?? d.selectedPoints?.[0]
    ?? null;
}

/** The row's attribute values as [{ column, value }]. Nulls dropped. */
function pointAttributes(point) {
  if (!point) return [];
  const list = v => [].concat(v ?? []);          // docs sample shows a single object, field notes an array
  const attrs = list(point.selectedAttributes).length
    ? list(point.selectedAttributes)
    : list(point.deselectedAttributes);          // table measure-cell click
  return attrs
    .map(a => ({ column: a.column?.name, value: a.value }))
    .filter(a => a.column && a.value != null && a.value !== '' && a.value !== '{Null}');
}

const BUCKET = /^(Day|Week|Month|Quarter|Year)\((.+)\)$/i;

/** "Month(Order Date)" becomes { bucket: 'month', name: 'Order Date' }. */
function splitBucket(column) {
  const m = BUCKET.exec(String(column).trim());
  return m ? { bucket: m[1].toLowerCase(), name: m[2] } : { bucket: '', name: column };
}

/** Epoch seconds (accepts seconds or milliseconds). */
function toEpochSec(v) {
  const n = Number(v);
  return n >= 1e11 ? Math.floor(n / 1000) : n;
}

/** Inclusive last second of a week/month/quarter/year bucket, in UTC. */
function bucketEndSec(bucket, startSec) {
  const d = new Date(startSec * 1000);
  const y = d.getUTCFullYear(), mo = d.getUTCMonth(), da = d.getUTCDate();
  const next = {
    week: Date.UTC(y, mo, da + 7),
    month: Date.UTC(y, mo + 1, 1),
    quarter: Date.UTC(y, mo - (mo % 3) + 3, 1),
    year: Date.UTC(y + 1, 0, 1),
  }[bucket];
  return Math.floor(next / 1000) - 1;
}

import { LiveboardEmbed, EmbedEvent, HostEvent, RuntimeFilterOp } from '@thoughtspot/visual-embed-sdk';

const SUMMARY_LB = '<summary-liveboard-guid>';
const DETAIL_LB  = '<detail-liveboard-guid>';
const DRILL_VIZ  = '<viz-guid>';        // '' = drill from any viz on the board

let embed = renderSummary();

function renderSummary() {
  hideBackButton();
  const e = new LiveboardEmbed('#ts-embed', { liveboardId: SUMMARY_LB });
  e.on(EmbedEvent.VizPointClick, onPointClick);
  e.render();
  return e;
}

/** A clicked attribute becomes a runtime filter the detail Liveboard honors. */
function toRuntimeFilter({ column, value }) {
  const { bucket, name } = splitBucket(column);
  if (!bucket) return { columnName: name, operator: RuntimeFilterOp.IN, values: [String(value)] };
  const start = toEpochSec(value);                       // NUMBER, UTC
  if (bucket === 'day') return { columnName: name, operator: RuntimeFilterOp.IN, values: [start] };
  // Month / quarter / year clicks give the START of the bucket: send the whole range.
  return { columnName: name, operator: RuntimeFilterOp.BW_INC, values: [start, bucketEndSec(bucket, start)] };
}

async function onPointClick(payload) {
  const vizId = payload?.data?.vizId;
  if (DRILL_VIZ && vizId && vizId !== DRILL_VIZ) return;

  const clicked = pointAttributes(clickedPoint(payload)).map(toRuntimeFilter);
  if (!clicked.length) return;                           // nothing to scope by

  // Filters the user already set on the board. Optional: fall back to the click alone.
  const source = embed;
  let boardFilters = [];
  try {
    // The docs disagree on the envelope: the SDK reference types it { liveboardFilters, runtimeFilters },
    // the host events page describes an array. Accept both, and both item keys (`column` was observed).
    const res = await source.trigger(HostEvent.GetFilters);
    const list = Array.isArray(res) ? res : (res?.liveboardFilters ?? []);
    boardFilters = list
      .map(f => ({ columnName: f.column ?? f.columnName, operator: RuntimeFilterOp[f.operator] ?? RuntimeFilterOp.IN, values: f.values }))
      .filter(f => f.columnName && Array.isArray(f.values) && f.values.length);
  } catch { /* click only */ }
  if (embed !== source) return;                          // user navigated while we waited

  // One entry per column. The clicked value wins over a board filter on the same column.
  const byCol = new Map();
  [...boardFilters, ...clicked].forEach(f => byCol.set(f.columnName, f));
  openDetail([...byCol.values()]);
}

function openDetail(runtimeFilters) {
  embed.destroy();                                       // always destroy before re-render
  embed = new LiveboardEmbed('#ts-embed', { liveboardId: DETAIL_LB, runtimeFilters });
  embed.render();
  showBackButton(() => { embed.destroy(); embed = renderSummary(); });
}

import { LiveboardEmbed, EmbedEvent, CustomActionsPosition, CustomActionTarget } from '@thoughtspot/visual-embed-sdk';

const ACTION_ID = 'view-records';
const PAGE_SIZE = 100;

const embed = new LiveboardEmbed('#ts-embed', {
  liveboardId: '<summary-liveboard-guid>',
  customActions: [{
    id: ACTION_ID,
    name: 'View records',
    position: CustomActionsPosition.CONTEXTMENU,    // the right-click menu
    target: CustomActionTarget.VIZ,                 // per viz, so the clicked row is sent
    metadataIds: { vizIds: ['<viz-guid>'] },        // scope with vizIds ALONE (keys are OR'd)
  }],
});

embed.on(EmbedEvent.Error, (e) => {
  // Field-observed, not in the docs: a right-click on a viz outside vizIds reports this code.
  if (JSON.stringify(e).includes('VIZ_ACTION_FILTER_VALIDATION')) return;
  showError(e);
});

embed.on(EmbedEvent.CustomAction, (payload) => {
  if ((payload?.id ?? payload?.data?.id) !== ACTION_ID) return;
  const scope = pointAttributes(clickedPoint(payload));   // e.g. [{ column: 'Day(Order Date)', value: 1769644800 }, ...]
  openRecordPanel(scope);
});
embed.render();

async function openRecordPanel(scope) {
  let offset = 0;
  const list = document.querySelector('#record-list');
  list.replaceChildren();

  async function loadPage() {
    const r = await fetch('/api/record-detail', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ scope, offset, size: PAGE_SIZE }),
    });
    const { columns, rows } = await r.json();
    rows.forEach(row => list.appendChild(recordRow(Object.fromEntries(columns.map((c, i) => [c, row[i]])))));
    offset += rows.length;
    // A SHORT page is the only reliable end-of-data signal.
    document.querySelector('#load-more').hidden = rows.length < PAGE_SIZE;
  }
  document.querySelector('#load-more').onclick = loadPage;
  await loadPage();
}

function recordRow(row) {
  const li = document.createElement('li');
  const a = document.createElement('a');
  a.textContent = `${row['Record Id']} · ${row['Customer Name']} · ${row['Amount']}`;   // textContent, never innerHTML
  const href = resolveLink('https://example.com/records/{Record Id}', row);
  if (href) { a.href = href; a.target = '_blank'; a.rel = 'noopener'; }
  li.appendChild(a);
  return li;
}

/** Fill {Column} placeholders and refuse anything that is not http(s). */
function resolveLink(template, row) {
  const url = template.replace(/\{([^{}]+)\}/g, (_, c) => encodeURIComponent(String(row[c.trim()] ?? '')));
  try { const u = new URL(url); return ['http:', 'https:'].includes(u.protocol) ? u.href : ''; }
  catch { return ''; }
}

const DETAIL_MODEL   = '<record-level-model-guid>';             // one row per record
const DETAIL_COLUMNS = ['Record Id', 'Order Date', 'Customer Name', 'Amount'];
const SCOPE_COLUMNS  = new Set(['Order Date', 'Employee Name', 'Territory', 'Region']);   // allowlist

/** MM/DD/YYYY in UTC: the date literal the search parser accepted on the cluster tested. */
function mdy(sec) {
  const d = new Date(sec * 1000), p = n => String(n).padStart(2, '0');
  return `${p(d.getUTCMonth() + 1)}/${p(d.getUTCDate())}/${d.getUTCFullYear()}`;
}

function buildQuery(scope) {
  const clauses = [];
  for (const { column, value } of Array.isArray(scope) ? scope : []) {
    const { bucket, name } = splitBucket(column);          // same helper as the frontend
    if (!SCOPE_COLUMNS.has(name)) continue;                // the browser cannot choose columns
    const clean = String(value).replace(/['\\]/g, '');   // strip quotes AND backslashes: literals are single-quoted
    if (!bucket) { clauses.push(`[${name}] = '${clean}'`); continue; }
    const start = toEpochSec(value);
    if (bucket === 'day') clauses.push(`[${name}] = '${mdy(start)}'`);
    else clauses.push(`[${name}] >= '${mdy(start)}' [${name}] <= '${mdy(bucketEndSec(bucket, start))}'`);  // verify on your cluster
  }
  return [DETAIL_COLUMNS.map(c => `[${c}]`).join(' '), ...clauses].join(' ');
}

app.post('/api/record-detail', async (req, res) => {
  const token = await getTokenForUser(req.user);           // the SAME per-user token the embed uses
  const size  = Math.min(Number(req.body.size) || 100, 1000);   // your own page cap
  const r = await fetch(`${TS_HOST}/api/rest/2.0/searchdata`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify({
      query_string: buildQuery(req.body.scope || []),
      logical_table_identifier: DETAIL_MODEL,
      data_format: 'COMPACT',
      record_offset: Math.max(Number(req.body.offset) || 0, 0),
      record_size: size,
    }),
  });
  if (!r.ok) {                                             // log upstream detail server-side only
    console.error('searchdata', r.status, await r.text());
    return res.status(502).json({ error: 'Could not load records' });
  }
  const content = (await r.json()).contents?.[0] ?? {};
  res.json({ columns: content.column_names ?? [], rows: content.data_rows ?? [] });
});

You can run all three on the same Liveboard.

The cost, volume and compliance columns are our assessment of the trade-offs, not doc-stated. The security column is doc-stated for runtime filters and for calling as the viewer.

ThoughtSpot's menu items Action.DrillDown, Action.DrillInclude, Action.DrillExclude and Action.ShowUnderlyingData work without any code docs. Three levers exist:

• Remove or grey out. hiddenActions removes items, disabledActions greys them out, visibleActions is an allowlist. Set either hidden or visible, not both docs.
• Trigger it yourself. HostEvent.DrillDown takes points (clickedPoint, selectedPoints) and either a columnGuid or autoDrillDown (the most popular column). vizId is required in a Liveboard context TS 9.8.0.cl+ docs.
• Listen for it. EmbedEvent.Drilldown fires after a drill-down happened docs.

liveboardEmbed.on(EmbedEvent.VizPointDoubleClick, (payload) => {
  liveboardEmbed.trigger(HostEvent.DrillDown, {
    points: {
      clickedPoint: payload.data.clickedPoint,
      selectedPoints: payload.data.selectedPoints,
    },
    autoDrillDown: true,          // or columnGuid: '<column-guid>'
    vizId: payload.data.vizId,    // TS 9.8.0.cl+, required on a Liveboard
  });
});

init({
  // ...
  customizations: {
    style: {
      customCSS: {
        rules_UNSTABLE: {
          // 'view-records' = the id of your custom action
          '[data-testid="popover-container"]:has([id="view-records"]) #context-menu-item-show-underlying-data': {
            display: 'none !important',
          },
        },
      },
    },
  },
});

• Privilege. The REST reference says that with role-based access control enabled, searchdata also requires the CAN_DOWNLOAD_DETAILED_DATA privilege, plus at least view access to the data source docs. The RBAC page labels that privilege Early Access and says support must enable it docs; the August 2026 release notes call the granular download privileges generally available docs. The docs conflict; confirm the state on your cluster.
• Plan for a refusal. Because the privilege gates the call, a user without it may be refused. Show a clear message for 401, 403 and 500 responses instead of an empty panel. Once the granular privileges are enabled, DATADOWNLOADING ceases to exist, and users who had it receive both new privileges automatically while others must be granted them manually docs.
• A record list is a data export in practice. Our guidance: if you hide the CSV and XLSX download actions for a group, decide on purpose whether your panel should show the same rows to the same group. The docs gate only searchdata and the download privileges, not your UI.
• No trust in the browser. Your server picks the Model and columns and validates every clicked column against an allowlist. It quotes literals and drops anything it does not recognize.
• Runtime filters are not a boundary. In the left-click flow, the filters you pass are visible to and editable by the user. Enforce who sees what in ThoughtSpot (RLS, group membership, the token).

• Internal portal: row links back to internal systems (CRM, ERP, ticketing) are the main value. Keep the link template in configuration, and keep the http(s)-only check.
• AI and Spotter: custom actions can also target CustomActionTarget.SPOTTER with MENU or CONTEXTMENU, but modelColumnNames is not supported for that target docs. For native drill from a Spotter answer, HostEvent.DrillDown needs the Answer ID as vizId docs.
• Mobile and webviews: right-click is a mouse gesture, and the docs do not describe how a context menu is invoked on touch. Consider the MENU or PRIMARY positions, test on real devices, and render the detail panel full-screen.

ThoughtSpot runs in an iframe and cannot execute your JavaScript. A callback action is therefore a message: the user picks the item, the iframe emits EmbedEvent.CustomAction with an action id and some context, and your handler decides what to do. A URL action skips your app and has ThoughtSpot send the data directly to an endpoint. The docs do not mark either type as beta or early access docs.

Where you define a callback also matters. UI-defined actions are managed in ThoughtSpot and come as global (on by default for all visualizations, in the More menu) or local (assigned per viz, Answer, or Model). Position options there are primary, menu, and context menu docs, and visibility can be limited by user group docs. You create them under Develop > Customizations > Custom actions docs.

Code-based custom actions are callback-only and cover Liveboards, visualizations, Answers, and Spotter. They support sharing by groups and orgs, which the docs give as the reason to prefer them for portability docs. GA SDK 1.43.0+ · TS 10.14.0.cl+ docs The same option is on the Liveboard, App, Search, and Spotter view configs docs. The docs introduce the feature in the 10.14.0.cl release notes but do not label it GA explicitly.

Sources: CustomActionTarget, CustomActionsPosition, Spotter. CONTEXTMENU works only for the VIZ, ANSWER, and SPOTTER targets. The UI docs say ThoughtSpot allows only one primary action on a visualization page docs. If a primary-menu action is defined in both the UI and code, only the UI one shows docs. The docs' code examples sometimes spell the scope fields groupId and orgId; the interface table and the enum definitions say groupIds and orgIds, which is what this guide uses docs.

import { LiveboardEmbed, EmbedEvent, CustomActionsPosition, CustomActionTarget } from '@thoughtspot/visual-embed-sdk';

const embed = new LiveboardEmbed(el, {
  liveboardId,
  customActions: [{
    id: 'view-orders',                       // your contract with the handler
    name: 'View orders',                     // label users see
    position: CustomActionsPosition.CONTEXTMENU,
    target: CustomActionTarget.VIZ,
    metadataIds: { vizIds: ['<viz-guid>'] },   // scope: one viz only
  }],
});

embed.on(EmbedEvent.CustomAction, async (payload) => {
  const id = payload?.id ?? payload?.data?.id;      // Classic vs new experience
  if (id !== 'view-orders') return;
  const cmp = payload.contextMenuPoints ?? payload.data?.contextMenuPoints;
  const point = cmp?.clickedPoint ?? cmp?.[0];
  // Send the scope to YOUR backend, which re-checks it and queries with the user's token.
  await fetch('/api/orders', { method: 'POST', headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ attributes: point?.selectedAttributes ?? [] }) });
});
embed.render();

The id location differs: the docs show payload.id for classic Liveboards and payload.data.id for the new Liveboard experience and for Answer payloads docs. The payload type, CustomActionPayload, carries id (omitted on Liveboard-level code-based actions), vizId, embedAnswerData, contextMenuPoints, and session docs.

Getting the data behind the click

For the whole viz, use payload.answerService.fetchData(offset, size), which returns a page as { columns, data } docs AnswerService: SDK 1.25.0 · TS 9.10.0.cl+. Observed on 26.8.0.cl: the data is column-oriented (columnDataLite) and values can be JSON strings, so transpose and parse defensively Field-observed.

For record-level drill-through (right-click a number, list the rows behind it), see Drill-down and drill-through. That section covers choosing between a click event and a context-menu action, and fetching detail rows safely.

A URL action POSTs the Answer or viz data to a target. Authentication can be none, basic, bearer, or an X-API-Key header; the credentials are visible to other authenticated users, even without Developer or Admin privileges, so never put a powerful secret there. For embedded use the target domain must be on both the CORS allowlist and the CSP connect-src allowlist. localhost is unsupported (use 127.0.0.1), and the action is disabled on unsaved Answers docs. URL actions cannot be defined in code.

An action is a way for data to leave the iframe. These four controls limit how far. They are guidance assembled from the scoping and URL-action docs above, not a single documented checklist.

• Column scope picks vizzes, not cells. modelColumnNames (format "<modelGuid>::<columnName>") shows the action on visualizations built with the column. The docs describe this as the column's presence in a visualization and do not describe per-cell hiding, so check the clicked point in your handler and show a clear message docs.
• No Object IDs. The docs say code-based custom actions do not currently support Object IDs docs.
• Log what your handler did. Configuration problems surface through EmbedEvent.Error codes such as CUSTOM_ACTION_VALIDATION and CONFLICTING_ACTIONS_CONFIG docs. A handler that quietly ignores an unknown action id is invisible, so record the id, the outcome and your backend request id (our guidance).
• VIZ_ACTION_FILTER_VALIDATION is not fatal. If you route EmbedEvent.Error to a global error handler, filter it out Field-observed.
• answerService does not serialize. It is a live object, so it will not appear in JSON.stringify(payload), even though it is present Field-observed.
• File downloads work inside the iframe; window.print() does not. Build files in memory and save as a Blob Field-observed.

ThoughtSpot renders inside an iframe, so your page CSS cannot reach it. Instead you hand the SDK a customizations object at init() time and ThoughtSpot applies it inside the frame. The object has three parts: style (CSS), content (text), and iconSpriteUrl (icons) docs. A per-embed customizations also exists on view configs such as SpotterEmbedViewConfig and AppViewConfig docs.

Inside style you can load a CSS file with customCSSUrl, pass inline CSS with customCSS, or both. The file loads first and the inline CSS loads after it, so inline wins on conflict docs.

init({
  thoughtSpotHost,
  authType,
  customizations: {
    style: {
      customCSS: {
        variables: {
          '--ts-var-root-background': '#F7F5FF',
          '--ts-var-root-font-family': 'Poppins',
          '--ts-var-button--primary-background': '#5B3DF5',
        },
      },
    },
  },
});

customCSS: {
  rules_UNSTABLE: {
    // Why: hide filter option X. Re-test every release.
    '.bk-filter-option': { 'display': 'none !important' },
  },
}

init({
  thoughtSpotHost,
  authType,
  customizations: {
    style: { customCSSUrl: 'https://cdn.example.com/ts.css' },
  },
});

customizations: {
  content: {
    stringIDs: { 'Facet.objectType.pinboards': 'Dashboards' },
    // Risky: replaces every occurrence of "Spotter".
    // strings: { 'Spotter': 'dataAnalyzer' },
  },
}

customizations: { iconSpriteUrl: 'https://cdn.example.com/icons.svg' }

Hiding and disabling UI

Three view-config options control actions: hiddenActions removes them, disabledActions greys them out (disabledActionReason sets the tooltip), and visibleActions is an allowlist. Use either visible or hidden, not both docs. These change what the user sees. They do not stop an API call, so pair them with privileges.

Limits the docs state: object names, titles, descriptions, formulas and user-entered metadata are not translated automatically, and a currency set on upload does not change with locale. For your own UI-string translations the docs point to the Manual Translation REST APIs. docs The docs reviewed do not say how stringIDs overrides interact with a switched locale, so test each locale you ship. Whether to set locale from your app’s language or let the browser decide is a trade-off: matching your app is consistent, while the browser default respects individual users.

Feature parity: the docs say MCP with Spotter 3 support adds advanced analytics, reasoning, forecasting, automatic data source selection and deep research, and needs 26.2.0.cl or later docs. The docs do not publish a full parity matrix across the four options, so confirm the feature you need on your cluster.

The old names (ConversationEmbed, ConversationViewConfig, BodylessConversation) still work "until further notice" but are deprecated docs. The old agent endpoints /ai/agent/{conversation_identifier}/converse and /ai/agent/converse/sse are deprecated; use /ai/agent/conversation/{id}/send and /send/stream docs.

There are three modes: Spotter Classic, Spotter Agent (Spotter 2), and Spotter 3. Spotter 3 is available from 26.2.0.cl TS 26.2.0.cl+ and adds data-aware analysis, automatic data-model discovery, quick search and deep research, saved chats, and third-party MCP connectors. It is enabled per instance; contact your ThoughtSpot administrator. docs Early access What's new (February 2026) calls Spotter 3 Early Access and disabled by default on embedded instances. The AI embed page gives no status label for it, and only lists individual Spotter 3 features as GA. The FAQ labels Spotter 3 "Recommended" while What's new labels it Early Access, so confirm enablement with ThoughtSpot (neutral reading: recommended where enabled). The docs conflict on wording, so treat Spotter 3 as Early Access, confirm with ThoughtSpot that it is enabled, and do not assume GA. docs

Auto mode (worksheetId: 'auto_mode') lets Spotter 3 pick the data source. It is Spotter 3 only and disabled by default on ThoughtSpot Embedded instances; contact ThoughtSpot Support to enable it docs. Classic and Spotter 2 require a data source ID. In AppEmbed, spotterDataSources accepts 'auto_mode' SDK 1.52.0 · TS 26.10.0.cl docs.

const spotter = new SpotterEmbed(el, {
  frameParams: { height: '100%', width: '100%' },
  worksheetId: '<model-guid>',        // or 'auto_mode' (needs enablement)
  updatedSpotterChatPrompt: true,
  spotterSidebarConfig: {
    enablePastConversationsSidebar: true,
    spotterSidebarTitle: 'My conversations',
    spotterSidebarDefaultExpanded: true,
  },
  defaultQueryMode: SpotterQueryMode.RESEARCH, // SDK 1.52 / 26.9
  // DeepAnalysisPill needs SDK 1.53.0 / 26.10.0.cl
  hiddenActions: [Action.InConversationTraining, Action.DeepAnalysisPill],
});
spotter.render();
spotter.trigger(HostEvent.ResetSpotterConversation);

The two docs disagree on runtimeFilters in Spotter. The SpotterEmbedViewConfig reference says SDK 1.41.0 and TS 10.13.0.cl docs, while the changelog announces runtime filters and parameters in Spotter under SDK 1.42.0 docs. If you are on 1.41.x, test it before relying on it.

• Early access SpotterViz: an AI panel that builds visualizations when a Liveboard is in edit mode. It is disabled by default; contact ThoughtSpot Support to enable it. Brand it with spotterViz: SpotterVizConfig (starter prompts use SpotterVizStarterPrompt) docs.
• Early access Analysts: analyst agents in the Spotter sidebar, each scoped to a data model and skill set docs. The embed's Analysts section is disabled by default docs.

• Give columns clear names, descriptions, and synonyms in the Model. Spotter reads them.
• GA Coaching (reference questions and business terms) is on by default in embed from 26.2.0.cl. Hide Add to Coaching for end users with Action.InConversationTraining docs.
• Set global natural-language instructions with POST /api/rest/2.0/ai/instructions/set. Instructions must not exceed 3000 characters, the token must be scoped to the model's Org, and you need CAN_MANAGE_SPOTTER plus edit access or SPOTTER_COACHING_PRIVILEGE on the model docs.
• Privileges: CAN_USE_SPOTTER to use it; CAN_MANAGE_SPOTTER for global coaching and instructions (it does not grant model editing) docs. Delegate access with SPOTTER_COACHING_PRIVILEGE (TS 26.3.0.cl) docs.

• Recipients outside the tenant. Schedules take ThoughtSpot users or groups as principals, plus emails for non-users docs. Webhook payloads mark recipients as USER or EXTERNAL_EMAIL docs. A recipient domain allowlist is not stated in the docs searched; if you need one, enforce it in your own scheduling UI (our guidance).
• Schedule ownership. A schedule records an author, and scheduling for others needs JOBSCHEDULING or ADMINISTRATION. Whether a schedule keeps running after its author loses access is not stated. Inventory schedules with /schedules/search and review them on a cadence (our guidance).
• Limits. Documented: XLSX max 255 sheets, PNG up to 3840px wide. No report-specific row, size or rate limit was found in the docs searched; the cluster-wide REST rate limit still applies (see Running it in production). Load-test with your largest Liveboard instead of assuming.
• Exfiltration. Privilege split with RBAC: CAN_DOWNLOAD_DETAILED_DATA for CSV and XLSX, CAN_DOWNLOAD_VISUALS for PNG and PDF docs. Granting visuals but not detailed data is a common way to allow screenshots without raw rows (our guidance).

transient_content comes from the SDK getExportRequestForCurrentPinboard host event, for exports that include unsaved changes docs. From SDK 1.48 read the payload from result.data.v2Content, not result.v2Content docs. This was a breaking change in 1.48, so check any code written against 1.47 or earlier.

POST /api/rest/2.0/report/liveboard exports a Liveboard as PDF, PNG, CSV, or XLSX. Useful parameters: metadata_identifier, tab_identifiers, personalised_view_identifier (TS 10.9.0.cl+), visualization_identifiers, override_filters, runtime_filter, runtime_sort, runtime_param_override, regional_settings docs. Liveboard CSV (a zip of per-viz CSVs) and XLSX (one sheet per viz, max 255 sheets) need TS 26.2.0.cl+ docs.

POST /api/rest/2.0/report/answer exports an Answer as CSV (default), PDF, XLSX, or PNG. With RBAC enabled, the Answer PDF is a table PDF and needs CAN_DOWNLOAD_DETAILED_DATA docs. Its png_options, type (SAVED or PINNED), and personalised_view_identifier are Beta (TS 26.6.0.cl+). png_options takes x_resolution, y_resolution, and scaling.

POST /api/rest/2.0/report/liveboard
{
  "metadata_identifier": "<liveboard-guid>",
  "file_format": "PDF",
  "pdf_options": { "page_size": "A4" }
}

Who can download

• Without RBAC the DATADOWNLOADING privilege governs exports.
• With RBAC, CSV and XLSX need CAN_DOWNLOAD_DETAILED_DATA; PNG and PDF need CAN_DOWNLOAD_VISUALS docs. These granular privileges are GA per What's new (August 2026) but still Early Access on the RBAC page; the docs conflict, see Hardening.
• Liveboard-level download action IDs: Action.DownloadLiveboard, Action.DownloadLiveboardAsXlsx, Action.DownloadLiveboardAsCsv docs. Hiding them removes the button; the privilege is what stops the export.

Schedules are managed with POST /schedules/create, /schedules/search, /schedules/{id}/update (set status to PAUSE to pause or ACTIVE to resume), and /schedules/{id}/delete docs. Rules that bite:

• description is mandatory. file_format is CSV, PDF, or XLSX (default PDF).
• The schedule's PDF page_size enum is A4 or TAB_BASED. It has no CONTINUOUS, unlike the report API.
• On a mixed chart-and-table Liveboard a CSV schedule fails; use PDF or XLSX. Omit pdf_options and the PDF attachment may be empty docs.
• You need edit access, and ADMINISTRATION or JOBSCHEDULING to schedule for others (with RBAC, JOBSCHEDULING). Default time zone is America/Los_Angeles docs.

Send now. New Set isSendNowLiveboardSchedulingEnabled: true to add a "Send now" test email to the schedule modal. Related: Action, HostEvent, and EmbedEvent.SendTestScheduleEmail. The host event payload is { sendToSelf: boolean }; the embed event payload is { liveboardId, sendToSelf } (sendToSelf: false sends to all recipients) docs. The changelog marks it as a new feature in 1.48 and does not label it GA. Use it in QA so testers do not wait for the next cron tick.

liveboardEmbed.trigger(HostEvent.SendTestScheduleEmail, { sendToSelf: true });
// requires isSendNowLiveboardSchedulingEnabled: true on the embed

Webhooks. To receive scheduled output in your own system, create a webhook with POST /webhooks/create. The only event today is LIVEBOARD_SCHEDULE. Auth options: API_KEY, BASIC_AUTH, BEARER_TOKEN, OAUTH2. Add signature_verification (HMAC_SHA256) and verify it. You can set storage_destination to AWS_S3 (26.3.0.cl) or GCP_GCS (26.7.0.cl) so files land in your bucket, plus additional_headers (26.4.0.cl) and status (ENABLED or DISABLED, 26.7.0.cl). The update endpoint (/webhooks/{id}/update) also takes reset_options (26.7.0.cl) to clear the authentication, signature, or storage config. It needs ADMINISTRATION or DEVELOPER (or CAN_MANAGE_WEBHOOKS under RBAC) docs. Webhooks are Org-scoped, and the UI docs say only one webhook can be created per Org docs. To run the schedule yourself, see Scheduled report exports.

The built-in schedule is created with POST /api/rest/2.0/schedules/create. Its request has a cron frequency, a time_zone, recipient_details (ThoughtSpot principals plus plain emails), file_format (CSV, PDF, XLSX), optional liveboard_options (visualizations), pdf_options and a personalised_view_id. It has no filter, parameter or event-trigger field docs. Plain emails mean that "our users have no ThoughtSpot account" is not by itself a reason to leave it.

• Frequency. Minute-level schedules are no longer accepted from 26.8.0.cl and existing ones become hourly; sub-hourly needs Support docs. Your own scheduler is not bound by that, but every run is still a REST call.
• Content limits. A CSV schedule on a Liveboard that mixes charts and tables fails; use PDF or XLSX docs.
• Run history. schedules/search can return recent runs with include_history_runs docs. With your own scheduler, run history is yours to build.
• Webhook payload. A multipart request with the file and a JSON payload; msgUniqueId can be used for deduplication docs. Details of webhooks and storage destinations are in Exports, scheduling, and delivery.

With your own scheduler, the token your worker uses decides which rows end up in the file. Use auth/token/custom when your row-level security depends on variable values carried in the token (ABAC via RLS). If your RLS comes only from user properties and group membership, the docs list the full token for that case docs. Either way the secret key stays on the server.

• The export needs at least view access to the Liveboard, plus the download privilege for the format (DATADOWNLOADING, or CAN_DOWNLOAD_DETAILED_DATA for CSV and XLSX and CAN_DOWNLOAD_VISUALS for PDF and PNG under granular RBAC) docs.
• In a multi-Org setup the custom token takes org_identifier to scope the Org docs. Mint per Org, and see Who each person becomes.
• Admins bypass RLS (see Data security), so avoid running a customer-facing report with an admin identity.

This table is our guidance, not doc-stated. The docs describe the endpoints; the mapping to a business pattern is a judgement you can overrule.

POST /api/rest/2.0/report/liveboard accepts three override mechanisms. Which one a binding uses depends on whether the column already has a Liveboard filter docs.

POST /api/rest/2.0/report/liveboard
Authorization: Bearer <token minted for this audience>
{
  "metadata_identifier": "<liveboard-guid>",
  "file_format": "PDF",
  "override_filters": [
    { "column_name": "Close Date",
      "date_filter": { "type": "EXACT_DATE", "op": "EQ", "epoch": 1759622400 } },
    { "column_name": "Close Type",
      "generic_filter": { "op": "IN", "values": ["Regular"] } }
  ],
  "runtime_filter": { "col1": "Department", "op1": "EQ", "val1": "Sales" },
  "runtime_param_override": { "param1": "Currency", "paramVal1": "USD" }
}

• Dates. Send one filter object per date column; two on the same date column return an error. Epoch values are numbers, not strings, and the epoch is seconds since 1 Jan 1970 UTC, so convert time zones in your code docs docs. Supported types include EXACT_DATE, EXACT_DATE_RANGE (BW_INC), TODAY, YESTERDAY and LAST_N_PERIOD with datePeriod and number.
• Column names. Use the display name; for duplicates use WORKSHEET_NAME::COLUMN_NAME. GUIDs are not supported there docs.
• The file. The Liveboard response has no extension, so add .pdf, .xlsx, .png or .csv yourself. A multi-visualization CSV is a ZIP (26.2.0.cl+) docs. Always pass file_format, because the docs disagree on the default (see Exports).
• Where to put filters. Our guidance: keep every filter your scheduler controls at Liveboard level and test that a filter saved inside a visualization is not overridden; the docs searched do not state how that case behaves.
• Load. The call returns the file in the response, so a worker holds a connection for each export. Our guidance: queue the work, cap concurrency and retry with backoff, especially when one event hits many tenants. REST rate limits are covered in Running it in production.
• Fallback. If a Liveboard fights your filters, POST /api/rest/2.0/report/answer exports an Answer with runtime_filter and runtime_param_override, and names the file after the Answer title docs.

Four places could tell you what is already filtered. Only the first two read the saved state without a browser.

What does not exist (in the docs searched). No dedicated "get saved filters" endpoint. The Liveboard data response (metadata/liveboard/data) holds columns and rows, not filter definitions. report/liveboard returns a file. A PDF can include a page listing the applied filters (pdf_options.include_filter_page, default true), which a person can read but a program cannot use. We found no webhook or event that says "this Liveboard's filters changed". Treat a miss as "not found", not "proven absent", and re-check after each release.

The built-in schedule

• No filter field. schedules/create has no filter field, as covered above. The one handle on content is personalised_view_id, accepted on create and update since 10.10.0.cl GA docs.
• What a view is. A saved configuration of a Liveboard that includes specific filter selections docs. List a Liveboard's views with metadata/search, include_details and include_personalised_views. You get view_guid, view_name, author and is_public, but not the view's filter values docs. The one place the docs show a view's filters is the TML for views (view_filters with column, oper and values), and that page marks it Early Access docs.
• What the recipient copy contains. Not documented in what I found, including which row-level rules apply (see the open question in the model comparison above). What is documented: a schedule PDF can carry a filter page, and a webhook delivery names the view in viewInfo (viewId, viewName) and echoes the export request, including personalised_view_id and include_filter_page docs. It does not list filter values.
• Where an admin looks. The developer docs do not cover how an admin sees a schedule's effective filters in the product UI. Check the product documentation, and test with a view that has a filter.

A saved filter can change after a report is registered. Nobody tells your scheduler. These options are our guidance, because the docs are silent on this problem.

A cheap guard for any option: when the export errors on a filter conflict, stop that report, alert its owner and keep the other reports running.

A UI idea: show saved filters next to the bindings

In the screen where someone creates a report, load the Liveboard's saved filters and put each binding beside the one it will replace. The author sees, before saving, what the file will run with. This is an invented example (dummy ids, example.com recipients, invented columns):

Fill the "Saved on the Liveboard" column from one of the sources above, and show its read time ("read 2026-10-15 09:00"). A column that is saved on the Liveboard but missing from your bindings is the row people most often want to see.

An embed load has three phases: the SDK creates the iframe, the frame loads the ThoughtSpot app and authenticates, then the cluster runs the queries behind each visualization. The docs' own checklist covers all three: use the recommended SDK version, pick the right embed package (one Liveboard rather than many visualizations, and fullHeight: true to avoid inner scrolling), prefetch, call init early, cache results by tuning the warehouse, and serve over HTTP/2. docs

SDK 1.52.0 introduced a preRenderConfig object (the PreRenderConfig interface) that bundles pre-render settings. It takes precedence when both it and the old top-level properties are set, so existing code keeps working. The reference lists no cluster-version minimum for it. docs docs New

// Early, e.g. after sign-in: build the hidden embed.
const pre = new LiveboardEmbed('#analytics-host', {
  liveboardId,
  preRenderConfig: { id: 'main-board', containerSelector: '#prerender-stage' },
});
await pre.preRender();             // preRender(showPreRenderByDefault = false, replaceExistingPreRender = false)

// Later, when the user opens the page: same liveboardId, same flags, same id.
// The prerender guide shows a normal render() picking up the pre-rendered iframe.
const view = new LiveboardEmbed('#analytics-host', {
  liveboardId,
  preRenderConfig: { id: 'main-board' },
});
await view.render();               // methods also available: showPreRender(), hidePreRender(), syncPreRenderStyle(), getPreRenderIds()

Methods: preRender, showPreRender, hidePreRender, syncPreRenderStyle, getPreRenderIds. docs The example is our sketch of the documented API; the prerender guide has the canonical sample. In React use PreRenderedLiveboardEmbed. docs

fullHeight: true resizes the container to the Liveboard height so the page scrolls instead of the frame. On its own it loads all visualizations at once, which works best with fewer visualizations. With fullHeight: false (default), only visualizations in the viewport load first and the rest load as you scroll. docs

lazyLoadingForFullHeight gives you both: full height plus lazy loading, with lazyLoadingMargin (a CSS margin string) to start loading before a visualization scrolls into view. SDK 1.40.0+ · TS 10.12.0.cl+ docs The default depends on your SDK version. The property reference says false. From SDK 1.52.0, the changelog and lazy-load guide say it defaults to true whenever fullHeight is on for LiveboardEmbed or AppEmbed, together with enableScrollableContainerLazyLoading (true) and lazyLoadingMargin ('500px 0px'); any value you set, including false, overrides it. New docs docs

new LiveboardEmbed('#container', {
  liveboardId,
  fullHeight: true,
  lazyLoadingForFullHeight: true,   // note the exact key name; explicit on SDK < 1.52, default-on from 1.52
  lazyLoadingMargin: '100px',       // 1.52+ default is '500px 0px'
  minimumHeight: 400,                // only with fullHeight: true
});

minimumHeight (SDK 1.44.2 | TS 10.15.0.cl) applies only with fullHeight: true. The reference gives the older defaultHeight (SDK 1.5.0) the same description; prefer minimumHeight, which the guide documents. docs If the Liveboard sits in a scrollable or clipped container rather than the window, enableScrollableContainerLazyLoading computes the visible region against those ancestors; the reference shows no version for it, and the 1.52.0 changelog makes it default to true with fullHeight. docs docs

Liveboard data cache

enableLiveboardDataCache caches visualization data in the browser and adds a refresh control to the header, with a companion RefreshLiveboardBrowserCache event and host event. Early access The embed guide labels it an Early Access feature that is disabled by default; you contact ThoughtSpot support to enable it. The changelog entry (SDK 1.49.x) tags it only as new and does not call it GA. Confirm with support before relying on it. docs docs

Budgets and monitoring. The docs give no target render times or memory figures, so any number is yours to set (our guidance). Real-user timing shows true conditions but needs your telemetry; a synthetic check is steadier but misses real networks and data. Many teams use both. Track cold and warm renders separately, per strategy, using the timing sketch below.

Prefetch and init

Set callPrefetch: true in init(), or call the standalone prefetch(host, [PrefetchFeatures.LiveboardEmbed, PrefetchFeatures.VizEmbed]) before init. It only helps if it runs on an earlier page than the embed page. The best-practices page recommends calling prefetch before init, while the prerender guide notes that browser cache often makes prefetch redundant. docs docs Calling init() early at app start lets authentication run while the user is still on another page. docs

Many embeds on one page

• Prefer one Liveboard to several single-viz embeds; if you must, prefetch and keep to about four per page. docs
• Set queueMultiRenders: true in init() so each embed starts after the previous one completes, reducing browser load (SDK 1.5.0). docs
• Use showPreviewLoader (SDK 1.32.0 | TS 10.0.0.cl, viz embeds with vizId only) to show a preview image while a viz loads. docs

Fetch discipline in your own code

Your page often makes its own REST calls: listing Liveboards, loading filter values, discovering columns. The usual traps are not specific to ThoughtSpot. This is general engineering practice, not a documented rule:

• Do one fetch and derive from it. For example, load a filter's values once and compute dependent lists locally rather than calling per control.
• Cache by object id, and share an in-flight request between callers so two components asking for the same thing produce one call.
• Do not start a REST call per visualization on page load (an N+1 pattern); batch or defer until needed.
• Under cookieless trusted auth, send browser REST calls through the SDK's tokenizedFetch (SDK 1.28.0), which adds the bearer token the SDK already holds, so you do not mint a second one per call. docs See Authentication.

Measuring

The docs do not prescribe a measurement method; this is general practice. Mark performance.now() when you call render() and when LiveboardRendered fires, and log the difference by environment and strategy. Compare cold and warm loads separately. Check the browser network panel to see whether time is in assets, auth, or slow queries; query time points to the warehouse, which the docs list as a lever. docs

const t0 = performance.now();
embed.on(EmbedEvent.LiveboardRendered, () => {
  report('liveboard_render_ms', performance.now() - t0);
});
await embed.render();

enableV2Shell_experimental (SDK 1.31.2 | TS 10.0.0.cl) is documented as a lighter shell that "can provide performance benefits" but is experimental; do not use it in production without testing. docs

Separate instances per environment are also possible. Plan version order, because the docs advise against importing TML from a newer ThoughtSpot version into an older one. docs

Three ways to move TML

// POST /api/rest/2.0/vcs/git/commits/deploy  (CI step 1)
{ "branch_name": "test_deploy", "deploy_type": "DELTA", "deploy_policy": "VALIDATE_ONLY" }

// CI step 2: same call with deploy_policy "ALL_OR_NONE" and a commit_id for releases

ThoughtSpot's Git guidance suggests a main branch for actions and workflows (no TML), plus per-environment branches such as dev_vc, release, test_deploy, test_vc, uat_deploy, prod_deploy, prod_vc, and one version-control branch per single-tenant customer Org. This is guidance, not a requirement.docs

• Sharing, tags and custom actions on newly created objects: set them after deploy.docs
• Spotter coaching: coaching can be published to other Orgs, and users with SPOTTER_COACHING_PRIVILEGE can import and export coaching TML on the data model (26.3.0.cl+).docs
• Personalized Views: import with enable_personalized_view_upsert to update by obj_id instead of duplicating. Enabling it on your instance is a separate request to ThoughtSpot. Early access
• Spotter memory can be exported and imported between environments with /ai/memory/export and /ai/memory/import (26.8.0.cl). Import replaces the memory of the target data models rather than appending, so validate with dry_run first.docs

ThoughtSpot ships a new SDK version with each major Cloud release and tells you to use the recommended SDK version for your release. Each SDK symbol carries an "SDK x | ThoughtSpot y" badge, which is the minimum for both. Check it against your cluster before you use a flag.docs docs

SDK pinning strategy: options

Which option is right is your decision. The docs state only that you should use the recommended version and read the changelog. Whether a self-hosted copy beats npm is outside what the docs cover.

Recommended SDK per Cloud release

Source: What's new. The cloud-release rows are the "Upgrade notes" and "Recommended SDK versions" lines on that page.

The docs give the mechanics (Git, TML, validate, revert). The process around them is yours. Each row below separates what the docs state from our guidance.

Treat deprecations as dated work. The most urgent items for an embedder are below. The complete table, with replacements, is in What's new and feature status.