The Tableau Metadata API exposes the full content and lineage graph of a Tableau environment through GraphQL — every workbook, sheet, published data source, field, and database table, with the connections between them. It is the foundation for automated governance, impact analysis, and lineage documentation at enterprise scale.
The Tableau Metadata API is a GraphQL endpoint available on Tableau Server and Tableau Cloud that exposes the complete content and lineage graph of a Tableau environment. Every workbook, sheet, published data source, calculated field, database table, and database column — and every connection between them — is queryable through a structured API. For organisations managing Tableau at enterprise scale, the Metadata API is the foundation for automated governance, impact analysis, lineage documentation, and content auditing that would be impossible to maintain manually.
What the Metadata API Exposes
The Metadata API is built on a graph model. The central objects are:
**Workbooks** — with their sheets, dashboard layouts, data source connections, and embedded fields.
**Published data sources** — with their field definitions, calculated field formulas, database connections, and the workbooks that connect to them.
**Databases and tables** — the upstream data objects that feed data sources, with column-level detail.
**Fields** — calculated fields, with their formulas and dependencies on other fields and columns.
**Users and projects** — content ownership and permission structures.
The connections between these objects are the lineage graph: which workbooks connect to which published data sources, which data sources connect to which database tables, which fields depend on which other fields. This lineage is what makes the Metadata API powerful — not just cataloguing objects, but capturing the relationships between them.
Core GraphQL Queries
The Metadata API is accessed at /api/metadata/graphql on Tableau Server or via the Tableau Cloud URL. Authentication uses a Personal Access Token or session token obtained through the REST API.
A basic workbook query:
query {
workbooksConnection {
nodes {
name
projectName
owner {
username
}
sheets {
name
}
upstreamDatasources {
name
}
}
}
}
A lineage query — finding all workbooks that depend on a specific database table:
query {
databaseTablesConnection(filter: {name: "orders"}) {
nodes {
name
schema
database {
name
}
downstreamWorkbooks {
name
projectName
owner {
username
}
}
}
}
}
This query — identifying all workbooks downstream of the orders table — is the kind of impact analysis that would take days to perform manually across a large environment and takes seconds via the Metadata API.
Impact Analysis Use Cases
The Metadata API's lineage graph enables several categories of impact analysis that are otherwise impractical at scale:
**Schema change impact** — Before modifying a database table or column, query which published data sources connect to it and which workbooks depend on those data sources. Surface the full blast radius of the schema change before executing it.
**Data source deprecation** — Before retiring a published data source, identify all workbooks connected to it. Notify the owners of those workbooks. Coordinate the migration to a replacement data source. None of this coordination is possible without the lineage graph.
**Field dependency analysis** — Before modifying or removing a calculated field in a published data source, query which downstream fields in the same data source depend on it, and which workbook calculated fields reference it. Calculated field changes cascade in ways that are invisible without the dependency graph.
**Certification impact** — When promoting a data source to certified status, identify the workbooks that will immediately benefit from the certification badge, and the workbooks that are already using an uncertified version of the same underlying data.
Content Governance Automation
The Metadata API enables governance processes that would require manual audit without it:
**Stale content identification** — Query workbooks by last access date, identify content that has not been viewed in 90 days, and route it to an archival workflow. The REST API's workbook usage statistics combined with the Metadata API's content graph gives you both the what (which content is stale) and the why (what data sources and projects it belongs to).
**Orphaned content detection** — Identify published data sources with no downstream workbooks — data sources that are consuming extract refresh resources but serving no active analytics.
**Permission audit** — Query the permission structure of all content in a project, identifying workbooks with permissions that deviate from the project template. Governance at scale requires automated detection of permission drift.
**Calculation documentation** — Extract every calculated field formula from every published data source and generate a documentation catalogue. Formulas that were undocumented in Tableau are now systematically documented in an external catalogue.
Building a Metadata API Integration
A production Metadata API integration typically follows this pattern:
1. Authenticate to Tableau Server or Cloud via the REST API to obtain a session token or use a Personal Access Token.
2. Execute GraphQL queries against the Metadata API endpoint, paginating through large result sets using the cursor-based pagination that the API supports.
3. Transform the returned graph data into the format required by the downstream system — a data catalogue, a lineage visualisation tool, a governance dashboard, or a custom database.
4. Schedule the integration to run on a regular cadence — daily for most governance use cases, more frequently for environments with rapid content change.
Python is the most common implementation language, using the requests library for HTTP calls and json for response parsing. Tableau also provides the tableau-api-lib Python library, which wraps the REST and Metadata APIs with convenience methods.
For large environments, pagination is critical. The Metadata API returns up to 100 objects per page by default. A Tableau environment with 5,000 workbooks requires 50 API calls to retrieve the full workbook catalogue, with cursors passed between calls to page through the result set.
Metadata API vs REST API
The Metadata API and REST API serve different purposes and are complementary:
The **REST API** is for managing the environment — creating and deleting content, managing users and permissions, triggering refreshes, downloading workbooks. It is the operational API.
The **Metadata API** is for understanding the environment — cataloguing content, tracing lineage, auditing governance. It is the analytical API.
Most enterprise Tableau integrations use both. The REST API to manage; the Metadata API to understand.
A common pattern: use the Metadata API to identify stale content (content not accessed in 90 days with no downstream dependencies), then use the REST API to move that content to an archive project or delete it. The Metadata API informs the decision; the REST API executes it.
Limitations and Considerations
The Metadata API has limitations that enterprise users should understand before building production integrations:
**Eventual consistency** — The metadata graph is not updated in real time. There is a lag between when content changes occur in Tableau and when those changes are reflected in the Metadata API. For most governance use cases, this lag is acceptable. For near-real-time lineage, the lag is a constraint.
**Calculated field formula visibility** — The Metadata API returns calculated field formulas, but the formula representation may differ from what is displayed in the Tableau UI for complex nested calculations. Validate formula extraction against the Tableau Desktop display for critical calculations.
**Performance on large queries** — Deep lineage queries across large environments can be slow. Query optimisation — requesting only the fields needed, filtering aggressively, using pagination — is important for production integrations.
**Tableau Cloud vs Server differences** — Some Metadata API fields and objects are available on one platform but not the other. Consult the current Tableau documentation for platform-specific availability.
Our Tableau consulting practice builds Metadata API integrations for enterprise clients — lineage tools, governance dashboards, content catalogues. Contact us to discuss how the Metadata API can support your Tableau governance programme.
A former Microsoft data architect audits your data foundation, identifies your top priorities, and sends you a written plan. Free. No pitch.
Book a Call →