ThoughtSpot REST APIs
The ThoughtSpot REST API framework lets you create, access, and manage ThoughtSpot resources programmatically.
Overview🔗
You can use REST APIs to integrate ThoughtSpot capabilities into your applications and automate workflows, without going through the ThoughtSpot UI. ThoughtSpot REST API endpoints allow you to:
-
Manage users, groups, and roles. Create and manage user accounts, define groups and privileges, and automate provisioning workflows.
-
Authenticate and manage sessions. Get authentication tokens for users, including tokens for embedded application users with trusted authentication.
-
Manage metadata objects. Search, create, update, and delete objects such as Liveboards, Answers, Models, and Tables. Import and export objects as ThoughtSpot Modeling Language (TML) representations.
-
Query data. Run search queries against your data and fetch Liveboard, Answer, and visualization data in your application.
-
Export reports. Download Liveboards and Answers in PDF, PNG, CSV, or XLSX formats.
-
Automate deployments. Move content between environments and Orgs with TML and version control APIs, and manage multi-tenant deployments.
-
Administer your instance. Configure Orgs, manage connections, set up custom actions, audit activity with system logs, and manage instance settings.
-
Work with AI and Spotter. Create Spotter conversations, send messages, manage Spotter memory, and share conversations programmatically.
When to use REST APIs🔗
Use REST APIs when you need to:
-
Automate administration tasks such as user provisioning, group management, or scheduled content deployment.
-
Fetch data from ThoughtSpot into your own application or service, without embedding ThoughtSpot UI components.
-
Build deployment pipelines that promote content across development, staging, and production environments.
-
Integrate ThoughtSpot operations into external systems, such as CI/CD tooling, orchestration services, or custom portals.
If you want to embed interactive ThoughtSpot components such as Liveboards, Search, or Spotter in your application, use the Visual Embed SDK. The Visual Embed SDK and REST APIs are complementary; embedded applications commonly use REST APIs alongside the SDK for tasks such as token issuance for trusted authentication and metadata automation.
REST API versions🔗
ThoughtSpot REST APIs are available in the following versions:
-
REST API v2.0 (Recommended)
The REST API v2 framework includes a wider set of API endpoints with enhanced functionality and provides an interactive Playground for ease of use. -
REST API v1 (Deprecated)
The legacy REST API v1 endpoints let you create, edit, administer, and manage ThoughtSpot objects and data.ImportantThe REST API v1 endpoints are deprecated and replaced with the REST API v2 endpoints. Your existing integrations with REST API v1 endpoints will continue to function without disruption until March 2027. ThoughtSpot strongly recommends migrating your integrations to the REST API v2 endpoints.
For more information about the differences between these two REST API versions, see REST API v1 and v2.0 comparison.
REST API Playground🔗
ThoughtSpot provides an interactive playground to explore and try out API workflows on your own instance or ThoughtSpot trial instance.
To view the Playground, go to Develop > REST API > REST Playground v2.0 in your ThoughtSpot instance, or use the ThoughtSpot public instance.
In the Playground, you can:
-
Browse endpoints by resource category and view request and response schemas.
-
Try API requests against your instance and inspect live responses.
-
View and copy generated code samples for your requests.
Rate limits for API requests🔗
To ensure operational stability, optimize resource usage, and maintain service quality for all users, ThoughtSpot enforces rate limits on the number of public API requests allowed per client.
By default, a global rate limit of 100 requests per second (RPS) per client IP is enforced at the cluster level for all public APIs. This limit applies per client IP across all public APIs combined, not per individual endpoint. If a client IP exceeds this combined rate limit, a burst of up to 10 requests is allowed before requests are rejected with the HTTP 429: Too Many Requests error.
For async status endpoints such as /api/rest/2.0/metadata/tml/async/status, up to 100 requests per minute per client IP are allowed, with a burst of 100 requests before requests are rejected with an HTTP 429 error.
Org-level rate limit🔗
Starting from the 26.11.0.cl release, a rate limit of 50 RPS per Org is enforced at the application layer in ThoughtSpot instances with Orgs enabled. This limit is applied per Org across all public REST API endpoints combined.
The Org-level rate limit provides noisy-neighbor protection in multi-Org deployments. It ensures that API usage from one Org does not impact the service quality of other Orgs on the same cluster. If the Org-level limit is exceeded, the API returns an HTTP 429: Too Many Requests error.
The Org-level and cluster-level rate limits operate independently. A request can be rejected by either limit:
-
If a single client IP sends more than 100 RPS across the cluster, the cluster-level limit rejects the request.
-
If all clients in a single Org collectively send more than 50 RPS, the Org-level limit rejects the request.
Rate limit response🔗
When a request is rejected due to rate limiting, the API returns the HTTP/1.1 429 Too Many Requests response.
If your application receives an HTTP 429 response, reduce the request frequency or implement a retry mechanism with exponential backoff.
Adjusting rate limits🔗
The default rate limits are designed for typical production workloads. To request a change to the rate limits for your deployment, contact ThoughtSpot Support.
REST API SDKs🔗
To integrate v2.0 APIs into your applications faster, ThoughtSpot provides SDK libraries in several languages, including TypeScript and Python. The SDKs wrap endpoint calls, authentication, and typed request and response models. For more information, see REST API SDK libraries.