Get Started

To get started, review the requirements necessary to use the Tableau Metadata API.

In this section

Prerequisites

To use the Tableau Metadata API, the following requirements must be met:

For Tableau Cloud

Data Management: Tableau Cloud requires Data Management (or an edition that includes it) to access the Metadata API. This requirement started with Tableau Cloud October 2026. If you were using the Metadata API without Data Management at that time, you can continue doing so until June 2027.
An authentication token to programmatically access the Metadata API through the GraphQL endpoint. The Metadata API uses the same authentication process and token as the Tableau REST API. For more information, see How to Authenticate.

Note: The Metadata API is enabled automatically for Tableau Cloud sites with Data Management. If your site was upgraded from Standard, a site admin must turn on Catalog once. For more information, see Enable Tableau Catalog [↗].

For Tableau Server

Tableau REST API must not be disabled.
The Metadata API must be enabled. For more information about enabling the Metadata API, see the section below.
An authentication token to programmatically access the Metadata API through the GraphQL endpoint. The Metadata API uses the same authentication process and token as the Tableau REST API. For more information, see How to Authenticate.
Enable the Metadata API, as follows:

Tableau Server Only: Enable the Metadata API

The Metadata API is installed with Tableau Server but disabled by default.

A server admin must enable the Metadata API on Tableau Server using the tsm maintenance metadata-services enable command through the Tableau Services Manager (TSM) command line interface (CLI). For more information, see tsm maintenance [↗] topic in the Tableau Server Help.

Running the command begins initial ingestion, which is a component of the indexing process for the Metadata API.

Open a command prompt as an admin on the initial node (where TSM is installed) in the cluster.
Run the command: tsm maintenance metadata-services enable

Notes: When running this command, keep the following points in mind:

This command stops and starts some services used by Tableau Server, which causes certain functionality, such as the Recommendations capability, to be temporarily unavailable.
A new index of metadata is created at this time. Running this command any subsequent times will create and replace the previous index.

After the requirements have been met and the Metadata API has been enabled (for Tableau Server only) you can learn about the GraphQL schema or start querying the Metadata API.

About querying the Metadata API

To get the information you need from the Metadata API, you need to be able to write queries. Queries fetch metadata about the content published to your Tableau Cloud site or Tableau Server.

Before you can begin writing these queries, you need to understand what kind of Tableau Cloud or Tableau Server metadata is available through the Metadata API and the ways for accessing the metadata. For more information, see Understand the Metadata Model.

Who can query the Metadata API

In general, any authorized user can query the Metadata API.

Tableau Cloud requires Data Management to access the Metadata API, but Tableau Server does not. This requirement started with Tableau Cloud October 2026. If you were using the Metadata API without Data Management at that time, you can continue doing so until June 2027.

On Tableau Server without Data Management, if “derived permissions” is enabled, users can see external assets related to their Tableau content. For more information about derived permissions:

For Tableau Cloud: Permissions on external assets using derived permissions [↗]
For Tableau Server: Permissions on external assets using derived permissions [↗]

Query the API using the GraphQL endpoint

Unlike a REST API, the Metadata API has only a single endpoint. To use the Metadata API, issue queries against this metadata api endpoint using GraphQL.

The endpoint URI

http://<server-name>/api/metadata/graphql

Note:

The API endpoint and the in-browser tool that you can use to query GraphQL have distinct but very similar URLs:
- https://<server-name>/api/metadata/graphql is the API endpoint.
- https://<server-name>/metadata/graphiql/ is in-browser tool that you can use to query GraphQL.
Issue API calls against the endpoint URI. If you’re looking for a way to query the metadata API in a browser, see Explore the Metadata API schema using GraphiQL.
To use the GraphQL endpoint, you must authenticate using the Tableau REST API. For more information, see How to Authenticate topic.

Query

To form a query using GraphQL, you must specify the objects, and in some cases, objects within those objects until a unit of data can be returned.

query <query-name>{
  <object> (<arguments>){
    <attribute>
    <attribute>{
      <attribute>
    }
  }
}

Query example

query useMetadataApiToQueryOrdersDatabases{
  databases (filter: {name: "adventureworks"}){
    name
    tables{
      name
    }
  }
}

For more query examples, see the Example Queries topic.

Submitting the query

POST and Content-Type application/json

You typically submit GraphQL queries using POST and an HTTP Content-Type header of application/json, with the JSON-encoded query in the HTTP request body. A typical HTTP request body with a JSON-encoded simple GraphQL query might look like:

{"query":"query myquery{databases {name id}}"}

POST and Content-Type application/graphql

You can also submit GraphQL queries using POST and an HTTP Content-Type header of application/graphql. A typical HTTP request body with the same simple GraphQL query as above would be:

query myquery{databases {name id}}

GET

You can also submit GraphQL queries using GET and a querystring, with no request body at all. The querystring is a field-value pair where the field is query and the value is the GraphQL query, URL encoded. A typical HTTP request using the same simple GraphQL query as above would result in a URI and querystring like:

https://tableau.example.com/api/metadata/graphql?query=query%20myquery%7Bdatabases%7Bname%20id%7D%7D'

More information

For more information on typical GraphQL requests and expected interactions, see HTTP Methods, Headers, and Body [↗] on the GraphQL.org website.

Query response

The query returns only the data you specify in same shape as your query.

For the query example used above, you will see the following query response.

{
  "data": {
    "databases": [
      {
        "name": "adventureworks",
        "tables": [
          {
            "name": "AWBuildVersion"
          }
        ]
      },
      {
        "name": "adventureworks",
        "tables": [
          {
            "name": "SalesTerritory"
          },
          {
            "name": "Department"
          },
          {
            "name": "Culture"
          },
          {
            "name": "Address"
          },
          {
            "name": "Product"
          }
        ]
      },
      {
        "name": "adventureworks",
        "tables": [
          {
            "name": "CustomerAddress"
          },
          {
            "name": "Address"
          },
          {
            "name": "Customer"
          }
        ]
      }
    ]
  }
}

Permissions

Your query results are scoped to the permissions you’ve been granted. For more information, see How Permissions Work topic.

Errors

See Common Errors topic.

Explore the Metadata API schema using GraphiQL

One way to quickly get started with GraphQL queries and explore the Metadata API is to test queries against the schema. You can explore the schema using GraphiQL, which is an interactive in-browser tool. You can change the query as you like and see the results immediately.

Note: To access GraphiQL, you must sign in (authenticate) to your Tableau Cloud site or Tableau Server. The data you can see, specifically about external assets, is scoped to the permissions you’ve been granted. Tableau Cloud requires Data Management to access GraphiQL, but Tableau Server does not.

Open a browser and sign in to Tableau Cloud [↗] or Tableau Server 2019.3 (or later).
Copy the following partial URL: /metadata/graphiql/
In the browser’s address bar, delete everything after the “.com”.
Paste the partial URL after the “.com” and press ENTER or RETURN.

For example, if your site’s name is “MYCO” and the site URL is:

https://us-west-2b.online.tableau.com/#/site/MYCO/explore

The GraphiQL tool URL is:

https://us-west-2b.online.tableau.com/metadata/graphiql/

Note:

The API endpoint and the in-browser tool that you can use to query GraphQL have distinct but very similar URLs:
- https://<server-name>/api/metadata/graphql is the API endpoint.
- https://<server-name>/metadata/graphiql/ is in-browser tool that you can use to query GraphQL.
You can also access the GraphiQL in-browser tool from Tableau Catalog in Tableau Cloud site or Tableau Server by clicking Query metadata (GraphiQL) in the upper-right corner of the External Assets page.

About the GraphiQL query tool

The GraphiQL query tool is comprised of several parts.

Parts of the GraphiQL interface

History pane: After you have written and run a query, it’s saved to a list so that you can reuse the query at another time. To toggle the History pane, click the History button in the toolbar.
Left pane: Build queries in the left pane. To run a query, click the play button (Execute Query) in the Toolbar. For more information about writing queries, see Example Queries.
Query Variables pane: Use this pane to define the variables that you pass to your queries.
Toolbar: Use the toolbar to run queries, see a history of queries that you’ve run, and to explore the GraphQL schema.
Middle pane: See the results of and validate your queries in the right pane.
Right pane: Toggle this pane by clicking Documentation Explorer to show the GraphQL schema. You can search the schema to see the objects that are implemented by the Metadata API and the metadata that you can query.