# Cluster maintenance and upgrade

> For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt)

Source: https://developers.thoughtspot.com/docs/tse-cluster

# Cluster maintenance and upgrade

At any given time, a ThoughtSpot application instance can be in any one of the following states:

-   `ACTIVE`  
    When the cluster is running and user activity is detected.
    
-   `UNDER_MAINTENANCE`  
    When the cluster is temporarily unavailable because maintenance, upgrade, or patching is in progress.
    
-   `STOPPED`  
    When the cluster is inactive and no user activity is detected.
    
-   `STARTING`/`PENDING`  
    When the cluster is starting, or another workflow is currently in progress.
    

## Check whether a cluster is under maintenance

To determine whether a cluster is under maintenance, send a `GET` request to one of the following endpoints:

-   `GET /api/rest/2.0/system/banner` (Recommended)
    
-   `GET /tspublic/v1/admin/banner` (legacy REST API framework)
    

These APIs return banner information that indicates whether maintenance is in progress. Embedded applications can also use the banner text to inform users about the current cluster status.

### REST API v2 request

```cURL
curl -X GET \
--header 'Accept: application/json' \
'https://{ThoughtSpot-Host}/api/rest/2.0/system/banner'
```

### REST API v1 request

```cURL
curl -X GET \
--header 'Accept: application/json' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/admin/banner'
```

### API response

In the API response, check the following fields:

-   `under_maintenance`: A Boolean value that indicates whether the cluster is currently under maintenance.
    
-   `banner_text`: A user-facing message that describes the current system state.
    

> **NOTE:** Administrators of an embedded application can configure custom banner text to communicate maintenance status to users.

Example response when the cluster is under maintenance

{"banner\_text":"This system is currently under maintenance. Check back in a few hours.","under\_maintenance":true}

Example response when the cluster is operating normally

{"banner\_text":"This system is functioning normally. No maintenance is in progress.","under\_maintenance":false}

## Idle sensing and economy mode

If you use a ThoughtSpot Cloud instance for embedded deployments, you can enable idle sensing to reduce cost and allow the cluster to operate in economy mode.

When idle sensing is enabled, the cluster automatically stops after a period of inactivity. The default idle threshold is 120 minutes. To enable this feature on your cluster, contact ThoughtSpot Support.

### Get the status of an inactive cluster

When a cluster in economy mode has no user activity for 120 minutes, it transitions to the `STOPPED` state. If a user accesses a stopped cluster, the response headers include the cluster state.

```cURL
 $ curl https://{cluster-name}.thoughtspot.cloud  --head
  HTTP/1.1 200 OK
  Server: awselb/2.0
  Date: Tue, 30 May 2023 15:27:01 GMT
  Content-Type: text/html
  Content-Length: 3348
  Connection: close
  Cluster-State: Stopped
```

If the cluster is stopped, restart it by using the API described in the next section.

### Start an inactive cluster using API

On a standard ThoughtSpot Cloud cluster, users can restart an inactive cluster by using a Completely Automated Public Turing test to tell Computers and Humans Apart (CAPTCHA). For embedded deployments, CAPTCHA-based activation is not supported. Instead, send a GET request with the required query parameters:

-   `tse=true`
    
-   `start_cluster=true`
    

Production environment

```http
https://{ThoughtSpot-Host}/?tse=true&start_cluster=true
```

Staging environment

```http
https://{cluster-name}.thoughtspotstaging.cloud/?tse=true&start_cluster=true
```

Development environment

```http
https://{cluster-name}.thoughtspotdev.cloud/?tse=true&start_cluster=true
```

### Required headers

In the request header, you must include `security-key` and `X-Thoughtspot-Org-Id`.

`security-key`

Is required to authenticate your request when [trusted authentication is enabled]({{navprefix}}/{{trusted-auth-secret-key}}#trusted-auth-enable). ThoughtSpot Embedded users can obtain the `security-key` for their instance or Org context from their ThoughtSpot administrator.

`X-Thoughtspot-Org-Id`

If your instance has Orgs:

-   Specify the Org ID in the request header along with the security key of that specific Org context. If the security key does not match the Org ID, the API returns an error.
    
-   If the request header includes only the security key with no Org ID, it’s considered to be the security key of the global Org context (**All Orgs**). If it does not match the key generated for the All Orgs context, the API returns an error.
    
    When the cluster becomes available, users are logged into the Org context based on the key provided in the request.
    

The following example shows the cURL request for restarting a cluster:

```cURL
$ curl -X GET 'https://<cluster-name>.thoughtspot.cloud/?tse=true&start_cluster=true'  \
 -H  'X-Thoughtspot-Org-Id: {Org_Id}' \
 -H  'security-key: e8ade677-c3f1-461d-8b7f-7f0fe4e024f0'
```

If the `GET` request is successful, the cluster starts. When the cluster becomes available, users are signed in to the Org context associated with the provided key.

### Response header values

Note the cluster state in the response header:

-   `STARTING`  
    If the cluster is starting. It may take a few minutes to become active.
    
-   `UNKNOWN`  
    A possible error occurred. If the cluster does not start within 5 to 10 minutes, contact your administrator or ThoughtSpot Support.
    

```http
 HTTP/1.1 200 OK
 Server: awselb/2.0
 Date: Tue, 30 May 2023 16:04:08 GMT
 Content-Type: text/html
 Content-Length: 0
 Connection: keep-alive
 Cluster-State: Starting
```

### Response codes

 
| HTTP status code | Description |
| --- | --- |
| 
**200**

 | 

Successful operation

 |
| 

**400**

 | 

Invalid request

 |
| 

**401**

 | 

Unauthorized access

 |