A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Tableau API is how an app or AI agent works with a Tableau site: listing workbooks and views, pulling the data or an image behind a view, publishing and refreshing data sources, and managing projects, users, and groups. Access is granted by signing in for a credentials token, and what the agent can do is set by the site role and content permissions of the user it signs in as, not by per-method scopes. A state change, like an extract refresh succeeding, can be pushed to a registered webhook.
How an app or AI agent connects to Tableau determines what it can reach. There is the REST API for calling methods, webhooks for receiving events, and a first-party MCP server for agents, and each is governed by the credentials behind it and the site role and content permissions of the user those credentials belong to.
The REST API answers under /api/{version} on the Tableau Server or Tableau Cloud instance, where the version is a number like 3.29 in the path. A call signs in first to get a credentials token, then sends it as the X-Tableau-Auth header on every later request. Requests and responses are XML or JSON.
Tableau's official MCP server lets an agent reach a Tableau site through the Model Context Protocol, with tools to list and query data sources, list workbooks, read metadata, and pull view images. It is open source at github.com/tableau/tableau-mcp, runs self-hosted through npm (@tableau/mcp-server) or Docker, and authenticates with a personal access token.
A webhook posts a JSON payload to a registered HTTPS URL when a chosen event fires, like WorkbookRefreshSucceeded or DatasourceRefreshFailed. Webhooks are created, listed, and deleted through the REST API and are scoped to one site.
A personal access token signs in on behalf of a user without putting a username and password in code. It is the recommended way to authenticate automation. On Tableau Cloud a token expires after 15 consecutive days of non-use, and on Tableau Server after one year. The token carries the full site role and permissions of the user it belongs to.
Sign in with a Tableau username and password sent in the sign-in request body. It works the same way as a token but puts long-lived credentials in the request, so a personal access token is preferred for anything automated.
A connected app signs in with a JSON Web Token instead of a token or password, and can carry access scopes that limit which REST methods the session may call. This is the one Tableau path where access can be narrowed below the user's full permissions, and it is used for trusted server-to-server and embedding scenarios.
The Tableau REST API is split into areas an agent can act on, like workbooks, views, data sources, projects, and users. What an agent can do in each area is decided by the site role and content permissions of the user it signs in as, not by a per-method scope.
Sign in to a site with a personal access token or username and password, sign out, and switch to another site on the same server.
List workbooks on a site, read one, download its file, update its settings, and delete it.
List views on a site or in a workbook, read a view, and pull its data as CSV or as a rendered image.
List published data sources, read one, download its file, publish a new one, and trigger an extract refresh.
List projects, create one, update its name or hierarchy, and delete it along with its contents.
List the users on a site, add and remove users, list groups, and add or remove a user from a group.
List the sites on a server and read a single site's settings.
List the email subscriptions on a site and create a new one for a view or workbook.
List the prep flows on a site, read one, and run a flow to refresh its outputs.
List the asynchronous jobs on a site and read the status of a single job.
List the webhooks on a site, read one, create a new one for a chosen event, and delete it.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AuthenticationSign in to a site with a personal access token or username and password, sign out, and switch to another site on the same server.3 | ||||||
| POST | /api/{version}/auth/signin | Sign in to a site with a personal access token or a username and password, returning a credentials token. | write | — | Current | |
Open to any valid user. The returned token, sent as the X-Tableau-Auth header on later calls, carries that user's site role and content permissions; there are no per-endpoint scopes. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/auth/signout | Sign out and invalidate the current credentials token. | write | — | Current | |
Ends the session for the active token. A token also expires on its own, 240 minutes after sign in by default. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/auth/switchSite | Switch the current session to another site on the same server without signing in again. | write | — | Current | |
Only reaches sites the signed-in user is a member of. A credentials token is valid for one site at a time. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkbooksList workbooks on a site, read one, download its file, update its settings, and delete it.5 | ||||||
| GET | /api/{version}/sites/{site-id}/workbooks | List the workbooks on a site that the signed-in user can see. | read | View | Current | |
Returns only the workbooks the user has the View permission on. Acts onworkbook Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/workbooks/{workbook-id} | Read a single workbook's details. | read | View | Current | |
Needs the View permission on the workbook. Acts onworkbook Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/workbooks/{workbook-id}/content | Download a workbook as a .twb or .twbx file. | read | Download/Save a Copy | Current | |
Needs the Download Workbook/Save a Copy permission, which exposes the full workbook, including any embedded extract data. Acts onworkbook Permission (capability) Download/Save a CopyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/{version}/sites/{site-id}/workbooks/{workbook-id} | Update a workbook's settings, like its name, project, or owner. | write | Write | Current | |
Needs the Write permission on the workbook; changing the owner or project needs the matching project permission too. Acts onworkbook Permission (capability) WriteVersionAvailable since the API’s base version Webhook event WorkbookUpdatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/{version}/sites/{site-id}/workbooks/{workbook-id} | Delete a workbook and the assets that belong to it. | write | Delete | Current | |
Needs the Delete permission. This also removes the workbook's views and their data. Acts onworkbook Permission (capability) DeleteVersionAvailable since the API’s base version Webhook event WorkbookDeletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ViewsList views on a site or in a workbook, read a view, and pull its data as CSV or as a rendered image.5 | ||||||
| GET | /api/{version}/sites/{site-id}/workbooks/{workbook-id}/views | List the views inside a workbook. | read | View | Current | |
Needs the View permission on the workbook. Acts onview Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/views | List the views across a site, with optional usage statistics. | read | View | Current | |
Returns only the views the user can see. Usage statistics need the right site role. Acts onview Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/views/{view-id} | Read a single view's details. | read | View | Current | |
Needs the View permission on the view. Acts onview Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/views/{view-id}/data | Return the data behind a view as CSV. | read | View Summary Data | Current | |
Needs the View permission, and returns the summary data the view is built on, not just its picture. Acts onview Permission (capability) View Summary DataVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/views/{view-id}/image | Return a view rendered as a PNG image. | read | View | Current | |
Needs the View permission on the view. Acts onview Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data sourcesList published data sources, read one, download its file, publish a new one, and trigger an extract refresh.5 | ||||||
| GET | /api/{version}/sites/{site-id}/datasources | List the published data sources on a site. | read | View | Current | |
Returns only the data sources the user has the View permission on. Acts ondatasource Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/datasources/{datasource-id} | Read a single data source's details. | read | View | Current | |
Needs the View permission on the data source. Acts ondatasource Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/datasources/{datasource-id}/content | Download a data source as a .tdsx file. | read | Download Data Source | Current | |
Needs the Download/Save a Copy permission, which can include the extracted data inside the file. Acts ondatasource Permission (capability) Download Data SourceVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/sites/{site-id}/datasources | Publish a new data source to a site, or overwrite or append to an existing one. | write | Project: Publish | Current | |
Needs the Publish permission on the target project. Large files are sent through a separate file-upload session. Acts ondatasource Permission (capability) Project: PublishVersionAvailable since the API’s base version Webhook event DatasourceCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/sites/{site-id}/datasources/{datasource-id}/refresh | Start an extract refresh for a data source, without attaching it to a schedule. | write | Run Refresh | Current | |
Runs a full refresh by default. From version 3.28 the request body can ask for an incremental refresh. Returns a job to track with the Jobs methods. Acts ondatasource Permission (capability) Run RefreshVersionAvailable since the API’s base version Webhook event DatasourceRefreshStartedRate limitSubject to the per-site extract refresh quota SourceOfficial documentation ↗ | ||||||
ProjectsList projects, create one, update its name or hierarchy, and delete it along with its contents.4 | ||||||
| POST | /api/{version}/sites/{site-id}/projects | Create a project on a site, optionally nested under a parent project. | write | Site role: create projects | Current | |
Needs a site role that allows creating projects, such as a project leader or site administrator. Acts onproject Permission (capability) Site role: create projectsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/projects | List the projects on a site. | read | View | Current | |
Returns only the projects the user can see. Acts onproject Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/{version}/sites/{site-id}/projects/{project-id} | Update a project's name, description, or place in the hierarchy. | write | Project leader | Current | |
Needs project leader rights on the project, or site administrator. Acts onproject Permission (capability) Project leaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/{version}/sites/{site-id}/projects/{project-id} | Delete a project and every workbook and data source inside it. | write | Project leader | Current | |
Needs project leader rights or site administrator. This removes all of the project's content, not just the project record. Acts onproject Permission (capability) Project leaderVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & groupsList the users on a site, add and remove users, list groups, and add or remove a user from a group.6 | ||||||
| GET | /api/{version}/sites/{site-id}/users | List the users on a site. | read | Site administrator | Current | |
Needs a site administrator role to list all users. Acts onuser Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/sites/{site-id}/users | Add a user to a site with a chosen site role. | write | Site administrator | Current | |
Needs a site administrator role. From March 2026 the request can set the user's default language and locale. Acts onuser Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/{version}/sites/{site-id}/users/{user-id} | Remove a user from a site. | write | Site administrator | Current | |
Needs a site administrator role. Content owned by the user must be reassigned first. Acts onuser Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/groups | List the groups on a site. | read | Site administrator | Current | |
Needs a site administrator role to list groups. Acts ongroup Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/sites/{site-id}/groups/{group-id}/users | Add a user to a group. | write | Site administrator | Current | |
Needs a site administrator role. Group membership can carry content permissions, so this can widen what the user reaches. Acts ongroup Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/{version}/sites/{site-id}/groups/{group-id}/users/{user-id} | Remove a user from a group. | write | Site administrator | Current | |
Needs a site administrator role. Acts ongroup Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SitesList the sites on a server and read a single site's settings.2 | ||||||
| GET | /api/{version}/sites | List the sites on a server. | read | Server administrator | Current | |
Server only, and needs a server administrator role. Tableau Cloud exposes a single site instead. Acts onsite Permission (capability) Server administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id} | Read a single site's settings. | read | Site administrator | Current | |
Needs a site or server administrator role. Acts onsite Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscriptionsList the email subscriptions on a site and create a new one for a view or workbook.2 | ||||||
| GET | /api/{version}/sites/{site-id}/subscriptions | List the email subscriptions on a site. | read | Site administrator | Current | |
An administrator sees all subscriptions; other users see their own. Acts onsubscription Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/sites/{site-id}/subscriptions | Create an email subscription that sends a view or workbook on a schedule. | write | View | Current | |
The subscriber needs the View permission on the content. This sends scheduled email to the chosen recipient. Acts onsubscription Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FlowsList the prep flows on a site, read one, and run a flow to refresh its outputs.3 | ||||||
| GET | /api/{version}/sites/{site-id}/flows | List the prep flows on a site. | read | View | Current | |
Returns only the flows the user can see. Flows need the Data Management license. Acts onflow Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/flows/{flow-id} | Read a single flow's details. | read | View | Current | |
Needs the View permission on the flow. Acts onflow Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/sites/{site-id}/flows/{flow-id}/run | Run a flow now to refresh its output data sources. | write | Run Flow | Current | |
Needs the Run Flow permission and the Data Management license. Returns a job to track with the Jobs methods, and writes to the flow's real outputs. Acts onflow Permission (capability) Run FlowVersionAvailable since the API’s base version Webhook eventNone Rate limitSubject to the per-site flow run quota SourceOfficial documentation ↗ | ||||||
JobsList the asynchronous jobs on a site and read the status of a single job.2 | ||||||
| GET | /api/{version}/sites/{site-id}/jobs | List the active asynchronous jobs on a site. | read | Site administrator | Current | |
Needs a site administrator role. Supports filtering by job type, status, and created date. Acts onjob Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/{version}/sites/{site-id}/jobs/{job-id} | Read the status of a single asynchronous job, like an extract refresh or flow run. | read | View | Current | |
Available to the user who started the job, reporting its progress and result. Acts onjob Permission (capability) ViewVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList the webhooks on a site, read one, create a new one for a chosen event, and delete it.3 | ||||||
| GET | /api/{version}/sites/{site-id}/webhooks | List the webhooks on a site. | read | Site administrator | Current | |
Needs a site administrator role. Acts onwebhook Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/{version}/sites/{site-id}/webhooks | Create a webhook that posts to a URL when a chosen event fires. | write | Site administrator | Current | |
Needs a site administrator role. The event is named from the supported trigger events, like WorkbookRefreshSucceeded. Acts onwebhook Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/{version}/sites/{site-id}/webhooks/{webhook-id} | Delete a webhook so it stops sending notifications. | write | Site administrator | Current | |
Needs a site administrator role. Acts onwebhook Permission (capability) Site administratorVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Tableau can notify an app or AI agent when something happens on a site, like an extract refresh succeeding or a workbook being deleted, instead of the app repeatedly asking. Tableau posts the event to a webhook URL that has been registered for the chosen event.
| Event | What it signals | Triggered by |
|---|---|---|
WorkbookUpdated | Fires when a workbook is changed, like its name, project, or owner. | /api/{version}/sites/{site-id}/workbooks/{workbook-id} |
WorkbookDeleted | Fires when a workbook is deleted from a site. | /api/{version}/sites/{site-id}/workbooks/{workbook-id} |
WorkbookRefreshSucceeded | Fires when an extract refresh for a workbook completes successfully. | In-app only |
WorkbookRefreshFailed | Fires when an extract refresh for a workbook fails. | In-app only |
DatasourceCreated | Fires when a data source is published to a site. | /api/{version}/sites/{site-id}/datasources |
DatasourceRefreshStarted | Fires when an extract refresh for a data source begins. | /api/{version}/sites/{site-id}/datasources/{datasource-id}/refresh |
DatasourceRefreshSucceeded | Fires when an extract refresh for a data source completes successfully. | In-app only |
DatasourceRefreshFailed | Fires when an extract refresh for a data source fails. | In-app only |
ViewDeleted | Fires when a view is deleted. | In-app only |
Tableau limits how fast an app or AI agent can call, through a per-site request rate, and applies separate quotas to heavier work like extract refreshes that reset one or more times a day.
Tableau Cloud limits how fast an app or AI agent can call the REST API, with a per-site ceiling of about 1,600 calls per minute across all of that site's traffic. Heavier work has its own quotas on top: extract refreshes and scheduled tasks are limited in how often they can run, with quotas that reset one or more times a day, and from the 2026.1 release a new site is provisioned with a default of 10 concurrent extract refreshes. Going over any of these returns HTTP 429, and the response names a suggested retry time, such as retry after 146 seconds. Tableau Server does not apply the same fixed per-site rate, since limits there depend on how the server is sized and configured.
List methods page through results with the pageSize and pageNumber query parameters, where pageNumber is 1-based and pageSize defaults to 100 and tops out at 1,000. Each list response includes a pagination element giving the page number, page size, and total available count, so a caller can request the next page until the total is reached.
A list page returns at most 1,000 items, the maximum pageSize. Publishing a workbook, data source, or flow above the inline size limit of about 64 MB uses a separate file-upload session that sends the file in chunks under one upload id, rather than in a single request.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | 400006 Bad Request | The request was malformed, like an invalid page size or a body that does not match what the method expects. | Read the error summary and detail in the response, correct the request, and resend. |
| 401 | 401001 / 401002 Unauthorized | Sign-in failed, or the credentials token is missing, invalid, or expired. A token expires 240 minutes after sign in by default. | Sign in again to get a fresh credentials token and send it as the X-Tableau-Auth header. |
| 403 | 403xxx Forbidden | The signed-in user does not have the site role or content permission the request needs. | Grant the user the required permission or site role, then retry. |
| 404 | 404xxx Not Found | The resource does not exist on this site, or the credentials token cannot see it. | Confirm the id is correct and that the session is signed in to the right site. |
| 405 | 405000 Method Not Allowed | The HTTP method is not allowed on this URI, often a sign the wrong verb was used for the endpoint. | Use the method documented for the endpoint, such as GET to read or POST to create. |
| 429 | 429000 Too Many Requests | The request exceeded the per-site rate limit or an extract refresh quota. The response suggests a retry time. | Wait for the suggested retry time, then resend, and smooth the request rate. |
| 500 | 500000 Internal Server Error | An error on the Tableau side while handling the request. | Retry after a short wait, and contact Tableau support if it persists. |
Tableau versions its REST API by a major and minor number in the request path, where each Tableau Cloud and Server release adds a new version. The newest version is 3.29, shipped with the 2026.2 release.
Version 3.29 ships with the Tableau Cloud and Server 2026.2 release. The REST API version is named in the request path, like /api/3.29/, and each release adds a new version while older versions keep working for methods that existed in them.
Version 3.28 ships with the Tableau Cloud and Server 2026.1 release. It adds incremental extract refresh through the Update Data Source Now method and the ability to set a user's default language and locale.
Version 3.27 ships with the Tableau Cloud and Server 2025.3 release, continuing the per-release versioning where each platform release adds a new minor version of the REST API.
An integration pins a version in the request path and moves up on a schedule that suits it.
Tableau REST API what's new ↗Bollard AI sits between a team's AI agents and Tableau. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.