# tableau Api Explore in Tableau API (explore-tableau) - Full Documentation

<!-- document id=ebad38b33484dafb83c96517cb2e15a3d9b1665ac59dbc9e108fc1f6109e1ee6 url=/tableau/next/en-us/api/explore-tableau/docs/example-bash.md -->

# Bash Example

  

## Generating the JWT

A JSON Web Token (JWT) is a standard and secure way to transmit information between parties using JSON. General information about JWTs can be found at [jwt.io](https://jwt.io/).

`generate_api_token.sh`

```
#!/bin/bash

# Check if the API key is provided as an argument
if [ -z "$1" ]; then
  echo "Usage: $0 API_KEY"
  exit 1
fi

# Define the API key and header/payload
API_KEY="$1"
HEADER='{"alg":"HS256","typ":"JWT"}'
ISSUER="example.com"
SUBJECT="Example JWT"
ISSUED_AT=$(date +%s)

# Construct the payload
PAYLOAD="{\"iss\":\"$ISSUER\",\"sub\":\"$SUBJECT\",\"iat\":$ISSUED_AT}"

# Base64 encode the header and payload
base64_url_encode() {
echo -n "$1" | openssl base64 -e | tr -d '=' | tr '/+' '_-' | tr -d '\n'
}
HEADER_BASE64=$(base64_url_encode "$HEADER")
PAYLOAD_BASE64=$(base64_url_encode "$PAYLOAD")

# Create the signature
SIGNATURE=$(echo -n "$HEADER_BASE64.$PAYLOAD_BASE64" | openssl dgst -sha256 -hmac "$API_KEY" -binary | openssl base64 -e | tr -d '=' | tr '/+' '_-' | tr -d '\n')

# Combine the header, payload, and signature to form the JWT
JWT="$HEADER_BASE64.$PAYLOAD_BASE64.$SIGNATURE"

# Output the JWT
echo "JWT: $JWT"
```

## Sending the request

The code below requires bash script above.

This code requires the API key, the data provider string, a region, and a base64 URL encoded TDS specified as arguments. The script uses these elements to build a JWT and submit a request to the API gateway.

Note that the base64 URL encoded TDS string in this example has been replaced with `<BASE64_URLENCODED_TDS>` because the encoded TDS is too long to display comfortably here.

`send_upload_request.sh`

```
#!/bin/bash

# Echo usage if the three required arguments aren't provided
if [ -z "$4" ]; then
  echo "Usage: $0 SERVER_URL DATA_PROVIDER REGION API_KEY"
  exit 1
fi

# Get variables from arguments
server_url="$1"
data_provider="$2"
region="$3"
api_key="$4"

# Generate JWT
output=$(./generate_api_token.sh "$api_key")

# Extract the JWT, and hash from the output
jwt=$(echo "$output" | grep "JWT" | awk '{ print $2 }')

# The payload is a JSON object with name "tdsContent" and value of the base64 URLencoded TDS
payload='{
  "tdsContent": "<BASE64_URLENCODED_TDS>"
}'

# Send the POST request using curl
curl -i \
  -H "x-salesforce-region: $region" \
  -H "Content-Type: application/json" \
  -H "Authorization: C2C:$jwt" \
  -d "$payload" \
  $server_url/v1/upload-tds-content/$data_provider
```

<!-- document id=42055b5001282b62fb09bab80fc8c8bc6c3d9553805bb88eaf70f0fad529b491 url=/tableau/next/en-us/api/explore-tableau/docs/example-curl.md -->

# cURL Example

  

The cURL example below sends a request to the API gateway. Note that JWT generation is not included in this script. The JWT needs to be generated less than 5 seconds before it’s used for this authorization.

Replace:

- `<REGION>` with the Salesforce region
- `<BASE64_URLENCODED_TDS>` with the base64 URL encoded TDS

The JWT and URL used below are examples. Yours will be different, and the URL will depend on the data provider string you’re assigned.

```
curl \
--header 'Authorization: C2C:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsInN1YiI6IkV4YW1wbGUgSldUIiwiaWF0IjoxNzM0NzU3NTIxfQ.cg7nXc6vtmqBXM1E_H0UZ2bW7qajFmIctfHS-j0B1PA' \
--header 'x-salesforce-region: <REGION>' \
--header 'Content-Type: application/json' \
--data '{"tdsContent":"<BASE64_URLENCODED_TDS>"}' \
https://api.salesforce.com/analytics/integration/explore-in-tableau/v1/upload-tds-content/example
```

<!-- document id=2496a84f731fb31d19e753a41d2c94db2fe72ecd391a53225fc51650b32891ac url=/tableau/next/en-us/api/explore-tableau/docs/examples.md -->

# Examples

  

- [Python example](https://help.tableau.com/v0.0/api/explore-tableau/en-us/docs/example-python.html)
- [Java example](https://help.tableau.com/v0.0/api/explore-tableau/en-us/docs/example-java.html)
- [Bash example](https://help.tableau.com/v0.0/api/explore-tableau/en-us/docs/example-bash.html)
- [cURL example](https://help.tableau.com/v0.0/api/explore-tableau/en-us/docs/example-curl.html)
- [Example response](https://help.tableau.com/v0.0/api/explore-tableau/en-us/docs/example-response.html)

<!-- document id=c13a0e619f3f9cba0350c28fc9233d91225f5ca1329e7cd34650d17e7b38705c url=/tableau/next/en-us/api/explore-tableau/index.md -->

# Explore in Tableau API Overview

  

The _Explore in Tableau_ API allows Tableau partners to provide seamless, integrated experiences between their platforms or applications and their customer’s Tableau Cloud site. The API accepts an externally-defined data source and returns a URL for users to initiate a web authoring session. Leveraging this API, partners can help users reduce time to value by streamlining the experience of analyzing their data.

For example: You’re a cloud data provider, and your customers want to streamline their ability to analyze their data in Tableau. You can use the _Explore in Tableau_ API to create a button in your database application that launches Tableau-powered analytics for objects in the customer’s data catalog.

The _Explore in Tableau_ API is only available to Tableau partners, and is currently only available in Tableau Cloud. If you’re a partner who is interested in starting the on-boarding process for this feature, talk to your partner manager. For more information on becoming a Tableau partner, see [Tableau Partners](https://www.tableau.com/partners).

Once you have arranged access to the _Explore in Tableau_ API with your partner manager, you will receive an API key, a data provider string, and a rate limit threshold. Knowing the rate limit threshold is not required to use the API, but you should be aware of rate limitations for accurate troubleshooting.

## Overview

The _Explore in Tableau_ API is a single REST API method that accepts a base64 URL encoded Tableau Data Source (TDS) file in the request body. It returns a Tableau Cloud web authoring URL. Authorization is accomplished using an API key and a JSON Web Token (JWT). No customer data or content is transmitted during the API conversation except for TDS metadata (table and column names, etc.). Furthermore, the partner doesn’t need to know or have control of Tableau Cloud site or authorization information.

An end-to-end transaction using the _Explore in Tableau_ API is diagrammed below.

![Explore in Tableau process transaction diagram](/tableau/next/en-us/api/explore-tableau/en-us/assets/transaction-diagram.png)

1. The client triggers the data provider app (via click, for example) to explore data in Tableau.
2. The data provider calls the _Explore in Tableau_ API, uploading a custom TDS.
3. The API responds to the data provider with a URL.
4. The data provider directs the client to the URL.
5. The client launches a web authoring session using the TDS uploaded by the data provider.

## Prerequisites

- An understanding of JWTs and how to generate them. See [Examples](/v0.0/api/explore-tableau/en-us/docs/examples.html).
- The ability to generate a TDS using XML.
- Your assigned API key. Store your API key securely and avoid hardcoding it in your scripts.
- Your assigned data provider string.
- A Tableau Cloud connector exists for the data in question.
- Awareness of any data residency requirements.

<!-- document id=e13a32d471e7d0ba76119a8f61829f817aed583863f8c2c9c3b4eed809d1dee9 url=/tableau/next/en-us/api/explore-tableau/docs/example-java.md -->

# Java Example

  

## Generating the JWT

A JSON Web Token (JWT) is a standard and secure way to transmit information between parties using JSON. General information about JWTs can be found at [jwt.io](https://jwt.io/).

This example uses the [JJWT library](https://github.com/jwtk/jjwt).

```
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;

import java.security.Key;
import java.time.Instant;
import java.util.Date;

public class JwtGenerator {
    public static void main(String[] args) {
        if (args.length == 0) {
            System.out.println("Usage: java JwtGenerator <api_key>");
            System.exit(1);
        }

        String apiKey = args[0];
        
        // Define the key
        final Key key = Keys.hmacShaKeyFor(apiKey.getBytes());
        
        // Generate the JWT
        final String jwt = Jwts.builder()
            .setHeaderParam("typ", "JWT")
            .setIssuer("Put any value")
            .setSubject("Put any value")
            .setIssuedAt(Date.from(Instant.now())) // Use UTC for issued-at timestamp
            .signWith(key)
            .compact();
        
        System.out.println("Authorization: C2C:" + jwt.toString());
    }
}
```

## Sending the request

Replace:

- `<API_KEY>` with the API key
- `<REJOIN>` with the Salesforce region
- `<BASE64_URLENCODED_TDS>` with the base64 URL encoded TDS

```
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ExploreInTableau {
    public static void main(String[] args) throws Exception {
        String apiKey = "<API_KEY>";

        // Generate JWT using script from above
        String jwtToken = generateJwt(apiKey);
        HttpResponse<String> response = makeApiCall(jwtToken);

        if (response.statusCode() == 201) {
            System.out.println("Resource created successfully (201). No response body.");

            String locationHeader = response.headers().map().get("Location").get(0);
            if (locationHeader != null) {
                System.out.println("Location Header: " + locationHeader);
            } else {
                System.out.println("Location Header not found.");
            }
        } else {
            System.out.println("Failed to call API. Status Code: " + response.statusCode());
        }
    }
    
    public static HttpResponse<String> makeApiCall(String jwtToken) throws Exception {
        // Create an HTTP client (Java 11 and above)
        HttpClient client = HttpClient.newHttpClient();
    
        String apiUrl = "https://api.salesforce.com/analytics/integration/explore-in-tableau/v1/upload-tds-content/example";
    
        // Create the JSON payload (base64-encoded TDS content here)
        String jsonPayload = "{\"tdsContent\":\"<BASE64_URLENCODED_TDS>\"}";
    
        // Create the POST request with the necessary headers
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(apiUrl))
                .header("Authorization", "C2C:" + jwtToken)
                .header("x-salesforce-region", "<REGION>")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
                .build();
    
        return client.send(request, HttpResponse.BodyHandlers.ofString());
    }
}
```

<!-- document id=4a9f808809955c142a016ce260a6bc5bc31ecaae06cf4a281206755debd79fce url=/tableau/next/en-us/api/explore-tableau/docs/example-python.md -->

# Python example

  

## Generating the JWT

A JSON Web Token (JWT) is a standard and secure way to transmit information between parties using JSON. General information about JWTs can be found at [jwt.io](https://jwt.io/).

This example uses the [PyJWT library](https://pyjwt.readthedocs.io/). (Other JWT libraries may import properly but cause errors when called.)

`jwt_generator.py`

```
import sys
import jwt
import datetime
import hashlib
import hmac

def main(api_key):
   if not api_key:
       print("Usage: python jwt_generator.py <api_key>")
       sys.exit(1)

   # Define the key
   key = api_key.encode()

   # Generate the JWT
   payload = {
       "iss": "Put any value",
       "sub": "Put any value",
       "iat": datetime.datetime.utcnow()
   }

   jwt = jwt.encode(payload, key, algorithm='HS256')

   print(f"Authorization: C2C:{jwt}")

if ~name~ == "~main~":
   if len(sys.argv) < 2:
       print("Usage: python jwt_generator.py <api_key>")
       sys.exit(1)
  
   api_key = sys.argv[1]
   main(api_key)
```

## Sending the request

Replace:

- `<API_KEY>` with the API key
- `<REGION>` with the Salesforce region
- `<BASE64_URLENCODED_TDS>` with the base64 URL encoded TDS

The URL in the script below is an example. Yours will be different, and will depend on the data provider string you’re assigned.

```
import requests

def make_api_call(jwt_token):
    api_url = "https://dev.api.salesforce.com/analytics/integration/explore-in-tableau/v1/upload-tds-content/example"

    # Create the JSON payload (base64-encoded TDS content here)
    json_payload = {
        "tdsContent": "<BASE64_URLENCODED_TDS>"
    }
    
    headers = {
        "Authorization": f"C2C:{jwt_token}",
        "x-salesforce-region": "<REGION>",
        "Content-Type": "application/json"
    }
    
    # Send the POST request
    response = requests.post(api_url, json=json_payload, headers=headers)
    
    return response

# Main execution
if __name__ == "__main__":
    api_key = "<API_KEY>"
    
    # Generate JWT token
    jwt_token = generate_jwt(api_key)
    
    # Make the API call with the JWT token
    response = make_api_call(jwt_token)
    
    # Check response status code and handle accordingly
    if response.status_code == 201:
        print("Resource created successfully (201). No response body.")
        location_header = response.headers.get("Location")
        if location_header:
            print(f"Location Header: {location_header}")
        else:
            print("Location Header not found.")
    else:
        print(f"Failed to call API. Status Code: {response.status_code}")
```

<!-- document id=8bbc25bdd58040b801504e9e62fed862c9134fbf526b00857b2eff014ccf0481 url=/tableau/next/en-us/api/explore-tableau/docs/example-response.md -->

# Response Example

  

A successful request results in a `HTTP 201 CREATED` status, with an HTTP header named `location` that contains the Tableau Cloud web authoring URL.

```
date: Sat, 21 Dec 2024 05:15:16 GMT
location: https://online.tableau.com/vizql/showInstantAnalytics/example-dot-com/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/705318f93ad3029cc4a417778216591e
vary: Accept-Encoding, User-Agent
content-length: 0
```

<!-- document id=56c11069a799f4eece9ec14af982a77d7e5cb729e8af1173b20e633b230ffadb url=/tableau/next/en-us/api/explore-tableau/docs/using-the-api.md -->

# Using the API

  

The steps to use the API are:

1. Construct a TDS
2. Create a JWT
3. Make the request
4. Receive the response

## Construct a TDS

A Tableau Data Source (TDS) is an XML-formatted definition of a data source used in Tableau. This document does not cover the construction of a TDS.

## Create a JWT

The _Explore in Tableau_ API uses a JWT for authorization. The JWT has the following requirements:

- The algorithm (`alg`) in the header must be `HS256`.
- The type (`typ`) in the header must be `JWT`.
- The issuer (`iss`) claim is required, but can be any string.
- The subject (`sub`) claim is required, but can be any string.
- The issued at (`iat`) claim is required, and is expressed in unix time (non-leap seconds since the unix epoch). The API request must be submitted within 5 seconds of the `iat`.

For help on creating a JWT for the request, see [Examples](/v0.0/api/explore-tableau/en-us/docs/examples.html).

## Make the request

### Method

Submit the request using `POST`.

### URL

`https://api.salesforce.com/analytics/integration/explore-in-tableau/v1/upload-tds-content/{data-provider}`

Replace `{data-provider}` with your data provider string.

### Headers

<table><tbody><tr><td>HTTP Header</td><td>Possible Values</td><td>Notes</td></tr><tr><td><code class="language-plaintext highlighter-rouge">authorization</code></td><td><code class="language-plaintext highlighter-rouge">C2C:{jwt}</code></td><td>Replace <code class="language-plaintext highlighter-rouge">{jwt}</code> with the JWT. The request must be used within 5 seconds of JWT creation.</td></tr><tr><td><code class="language-plaintext highlighter-rouge">x-salesforce-region</code></td><td><code class="language-plaintext highlighter-rouge">us-east-1</code>&nbsp;(United&nbsp;States&nbsp;of&nbsp;America)<br><code class="language-plaintext highlighter-rouge">us-west-2</code>&nbsp;(United&nbsp;States&nbsp;of&nbsp;America)<br><code class="language-plaintext highlighter-rouge">ap-south-2</code>&nbsp;(India)<br><code class="language-plaintext highlighter-rouge">ap-southeast-3</code>&nbsp;(Indonesia)<br><code class="language-plaintext highlighter-rouge">ap-northeast-2</code>&nbsp;(South&nbsp;Korea)<br><code class="language-plaintext highlighter-rouge">ap-southeast-1</code>&nbsp;(Singapore)<br><code class="language-plaintext highlighter-rouge">ap-southeast-2</code>&nbsp;(Australia)<br><code class="language-plaintext highlighter-rouge">ap-northeast-1</code>&nbsp;(Japan)<br><code class="language-plaintext highlighter-rouge">ca-central-1</code>&nbsp;(Canada)<br><code class="language-plaintext highlighter-rouge">eu-central-1</code>&nbsp;(Germany)<br><code class="language-plaintext highlighter-rouge">eu-west-2</code>&nbsp;(United&nbsp;Kingdom)<br><code class="language-plaintext highlighter-rouge">eu-central-2</code>&nbsp;(Switzerland)</td><td>If your organization has data residency requirements, choose a region from the list that complies with those requirements. Otherwise, you should generally choose the region that’s closest to your data.</td></tr><tr><td><code class="language-plaintext highlighter-rouge">content-type</code></td><td><code class="language-plaintext highlighter-rouge">application/json</code></td><td>JSON is the only valid content type.</td></tr></tbody></table>

### Body

The request body is a JSON object composed of a single name-value pair. The name is `tdsContent`, and the value is the base64 URLencoded TDS.

For an example, see [Examples](/v0.0/api/explore-tableau/en-us/docs/examples.html).

## Receive the response

### Success response

A successful request returns an HTTP `201 Created` status. There is no response body.

The `location` header in the response contains a Tableau Cloud URL. A user navigating to the URL enters a web authoring session that uses the TDS as the data source. The user will be challenged for Tableau Cloud authentication if they aren’t already logged in.

### Error responses

<table><tbody><tr><td>Code</td><td>Reason</td><td>Details</td></tr><tr><td><code class="language-plaintext highlighter-rouge">400</code></td><td><code class="language-plaintext highlighter-rouge">Bad Request</code></td><td>Missing mandatory headers or fields, or the payload (TDS) is over 10MB.</td></tr><tr><td><code class="language-plaintext highlighter-rouge">403</code></td><td><code class="language-plaintext highlighter-rouge">Forbidden</code></td><td>Incorrect JWT or outdated timestamp (JWT <code class="language-plaintext highlighter-rouge">iat</code> claim is over 5 seconds old).</td></tr><tr><td><code class="language-plaintext highlighter-rouge">429</code></td><td><code class="language-plaintext highlighter-rouge">Too Many Requests</code></td><td>Rate limit exceeded.</td></tr><tr><td><code class="language-plaintext highlighter-rouge">500</code></td><td><code class="language-plaintext highlighter-rouge">Internal Server Error</code></td><td>An error occurred on the server.</td></tr></tbody></table>

<!-- document id=c01e4db5153bccfaa5d6a4acc6c1449b4fba3f1f4414f328aae830a88fe07eed url=/tableau/next/en-us/api/explore-tableau/docs/whats_new.md -->

# What's New

  

### August 2024

#### Added

Explore in Tableau API released for Tableau Cloud