Graphed LogoGraphed
Graphed LogoGraphed
FeaturesUse CasesIntegrationsPricing

How to Use Tableau REST API

Cody Schneider••9 min read

The Tableau REST API opens up a powerful way to automate and manage your Tableau Server or Cloud site programmatically. Instead of just clicking through the user interface, you can write scripts to handle repetitive tasks, integrate Tableau with other applications, and customize your data workflows. This article will guide you through the essentials of using the Tableau REST API, from making your first authenticated call to exploring common use cases.

GraphedGraphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Watch Graphed demo video

What Exactly is the Tableau REST API?

In simple terms, a REST API (Representational State Transfer Application Programming Interface) is a set of rules that allows different software applications to talk to each other over the internet. The Tableau REST API lets you manage Tableau content, users, permissions, and server processes using standard HTTP requests - the same protocol your web browser uses to fetch websites.

So, why would you use this instead of the regular Tableau interface? Three big reasons:

  • Automation: Imagine a script that automatically publishes daily sales reports, adds new team members from a spreadsheet, or checks the health of your server every hour. The API makes this kind of "set-it-and-forget-it" automation possible, saving countless hours of manual work.
  • Integration: You can embed Tableau functionality into your own applications or business portals. For example, a custom sales portal could use the API to request and display a specific, up-to-date sales dashboard for a logged-in user.
  • Custom Management: The API gives you granular control over your Tableau environment. You can build custom workflows for content management or user provisioning that perfectly match your organization's specific needs.

Getting Started: Your Pre-Flight Checklist

Before you can make your first API call, you need a few things in place. Think of this as getting your tools ready before starting a project.

1. Access to Tableau Server or Tableau Cloud: The REST API is designed to interact with a Tableau instance you have access to. You can't use it with Tableau Public.

2. A User with Permissions: You'll need credentials for a user on that server. To do anything meaningful, that user needs the right permissions. Site administrators and server administrators can do almost anything, while roles like Creator or Explorer might have more limited access. For this tutorial, using a Site Administrator account is easiest.

3. An API Client: This is the tool you'll use to send HTTP requests to the Tableau API. You have a few options:

  • Postman: A popular and user-friendly graphical application for testing APIs. It’s perfect for beginners because you can see everything visually without writing any code. We will use Postman for our examples here.
  • cURL: A command-line tool available on most operating systems. It's powerful but less intuitive if you aren't comfortable working in a terminal.
  • A Programming Language: For real automation, you'll likely use a language like Python or JavaScript. Python has excellent libraries like requests and even community-built Tableau libraries that simplify API interactions.

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

The First Step: Authentication

You can't just start asking the API for data, first, you have to prove who you are. The authentication process is your digital handshake with the Tableau server. In return for your credentials, the server gives you a temporary "token," which is like a secret key you'll include with all your future requests to prove you're authorized.

Here’s the process:

  1. You send your credentials (username/password or a personal access token) to the API's sign-in endpoint.
  2. The server validates your credentials. If they're correct, it generates a unique authentication token and also tells you the ID of the site you've logged into.
  3. You include this token in the header of every subsequent API call you make. This token typically expires after a few hours, at which point you’ll need to sign in again.

Step-by-Step Guide: Making Your First API Call with Postman

Let's walk through this process visually using Postman. The goal is simple: log in and then get a list of all the projects on our Tableau site.

Step 1: Get Postman Ready

If you don’t have Postman, download and install it. Open a new request tab. We’ll be sending a POST request, which is used for sending data to a server to create or update a resource.

Step 2: Sign In and Get Your Token

The first call is to the 'Sign In' endpoint. You'll need to construct the URL and the request body.

Set the request method to POST.

The URL will look like this, replacing your-server with your Tableau Server URL or Tableau Cloud pod:

https://your-server.com/api/3.19/auth/signin

(Note: 3.19 is the API version number. You should always check the latest version in the Tableau documentation, but this is a recent one that should work for most.)

Next, click on the "Body" tab in Postman, select the "raw" option, and choose "JSON" from the dropdown. This is where you'll put your login information. The structure looks like this:

{
 "credentials": {
  "name": "your_username",
  "password": "your_password",
  "site": {
   "contentUrl": "yoursite"
  }
 }
}
  • Replace your_username and your_password with your real credentials.
  • The contentUrl for your site is found in your 'Site' path in the Tableau Cloud URL after /site/. For Tableau Server's default site, you can leave this field empty by sending "".

Hit the "Send" button. If everything works, you’ll get back a successful 200 OK response with a JSON body containing your shiny new credentials token and your site ID.

The response will look something like this:

{
  "credentials": {
    "site": {
      "id": "c6a2e4e1-2f34-1234-abcd-1c8a6b4e7e9f",
      "contentUrl": "yoursite"
    },
    "user": {
      "id": "f5f6e7e8-e9ea-1234-abcd-2d9b8c7b6a5d"
    },
    "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
  }
}

Find the token value and the site id. You will need these for the next step!

GraphedGraphed

Your AI Data Analyst to Create Live Dashboards

Connect your data sources and let AI build beautiful, real-time dashboards for you in seconds.

Watch Graphed demo video

Step 3: Make Your First Authenticated Request

Now that you have your key (the token), let's unlock a door. We'll ask the API for a list of all projects on the site.

Open a new request tab in Postman.

Set the request method to GET, since we are retrieving information.

The URL identifies the resource you want. It's formed using the site ID you just got:

https://your-server.com/api/3.19/sites/c6a2e4e1-2f34-1234-abcd-1c8a6b4e7e9f/projects

Remember to replace your-server.com and the sample site-id with your actual server and site ID from the sign-in response.

This request won't work without your token. Go to the "Headers" tab in Postman. You need to add one key-value pair:

  • Key: X-Tableau-Auth
  • Value: Paste the long token string you received in the previous step.

Press "Send." If successful, you'll receive a 200 OK response containing a list of all the projects on your site, neatly structured in JSON format. Congratulations, you've successfully used the Tableau REST API!

Common API Use Cases & Examples

Getting a list of projects is great, but the real fun begins when you start automating more complex tasks.

Automating User Management

Manually adding, removing, or updating users is tedious, especially in large organizations. With the API, you can write a script that reads a list of users from a CSV file and provisions them in Tableau automatically.

To add a user, you'd send a POST request to /api/<version>/sites/<site-id>/users with a JSON body specifying the user's name and site role (e.g., Viewer, Explorer, Creator).

{
 "user": {
  "name": "new.user@example.com",
  "siteRole": "Explorer"
 }
}

Free PDF Guide

AI for Data Analysis Crash Course

Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.

Publishing Workbooks and Data Sources

This is an incredibly popular use case. If you have an automated process that generates daily or weekly .twbx files or data extracts, you can use the API to publish them directly to your Tableau Server. This is a multi-step process that involves initiating a file upload, uploading the file in chunks, and then committing the publish, but it’s the key to fully automating your BI pipeline.

Querying Metadata

Need a list of all dashboards that connect to a specific database? Or a list of all workbooks that haven't been viewed in over 90 days? The API allows you to query the metadata behind your Tableau content to answer these kinds of questions and power your own custom governance dashboards.

Best Practices and Pro Tips

As you work more with the API, keep these tips in mind:

  • Handle Pagination: When you request a large list of items (like users or workbooks), the API will often break the results into "pages." Your response will tell you the pageSize and the totalAvailable. To get all results, you'll need to make multiple requests, incrementing the pageNumber parameter in your URL each time.
  • Log Errors: API calls can fail. Your script or client should check the HTTP status code of the response. A 2xx code means success, while 4xx (like 401 Unauthorized or 404 Not Found) means you did something wrong, and 5xx codes typically indicate a server-side problem.
  • Don't Hardcode Credentials: Storing usernames and passwords directly in scripts is a security risk. Use Personal Access Tokens (PATs) instead of passwords whenever possible. They are more secure and easier to manage and revoke.
  • Version Your Requests: Tableau updates its API with new features over time. Specifying the version in your URL ensures your code continues to work as expected, even if Tableau releases a newer, breaking version of the API.

Final Thoughts

The Tableau REST API transforms Tableau from a standalone BI tool into a fully integrated and automated part of your larger data ecosystem. By learning to interact with it, you can eliminate manual reporting chores, build custom data applications, and manage your server environment with far more efficiency and control.

Mastering an API takes some practice, but a lot of the work is just automating the tedious steps to get to an answer. Here at Graphed, we focus on cutting out those steps entirely. We built a platform that connects your data sources - from marketing tools to a simple spreadsheet - and lets you create dashboards, build reports, and get plain-English answers using simple, natural language conversations. The goal is to get you from a question to an insight in seconds, not hours. Feel free to give Graphed a try and see if asking your data a question directly works better for you.

Related Articles