Skip to main content

Get Flow

Available June 2026 and later.

Retrieves detailed information about a specific Tableau Prep flow, including its output steps and optionally its input data connections and recent flow runs.

Registration gated

Registered only when FLOW_READ_TOOLS_ENABLED=true. When flow tools are disabled, get-flow (and list-flows) are not registered and their scopes are not advertised.

APIs called​

This tool reads flow metadata through the Tableau REST API (Tableau Cloud or Server) — not a local API. Invoking get-flow requires the tableau:mcp:flow:read MCP scope. The tool composes the minimum Tableau API (JWT) scopes needed per call: tableau:flows:read and tableau:mcp_site_settings:read are always requested, and the connections / runs sidecar scopes are added only when you opt into that sidecar — so a metadata-only call (includeConnections: false, includeFlowRuns: false) succeeds against a connected app that grants just tableau:flows:read (plus the always-on site-settings scope). Flows use the dedicated tableau:flows:read scope, not the tableau:content:read scope used by workbooks, data sources, and views. See OAuth configuration for details.

  • Read the flow's metadata and output steps. Issued against the Tableau REST API; requires the tableau:flows:read OAuth scope.
    • GET /api/{version}/sites/{siteId}/flows/{flowId} — query the flow's metadata, project, owner, and output steps. Query Flow
  • Read the flow's input data connections (only when includeConnections: true). Issued against the Tableau REST API; requires the tableau:flow_connections:read OAuth scope.
    • GET /api/{version}/sites/{siteId}/flows/{flowId}/connections — list the flow's input data connections. Query Flow Connections
  • Read recent flow runs (only when includeFlowRuns: true; requires Tableau REST API 3.10 or later). Issued against the Tableau REST API; requires the tableau:flow_runs:read OAuth scope.
    • GET /api/{version}/sites/{siteId}/flows/runs — list recent runs for the flow, filtered by flowId:eq:{flowId} and sorted startedAt:desc. Get Flow Runs

Required arguments​

flowId​

The ID of the flow, potentially retrieved by the List Flows tool.

Example: d00700fe-28a0-4ece-a7af-5543ddf38a82

Optional arguments​

includeConnections​

When true (default), additionally returns the input data connections for the flow.

If the connections sidecar call fails (e.g. permissions error), the tool still returns the flow metadata and emits a warning under mcp.warnings instead of failing the entire call.

When false, the tool also narrows the Tableau API scopes requested at JWT sign-in — it does not request tableau:flow_connections:read. This means a metadata-only call succeeds against a Connected App that grants only tableau:flows:read, even when the operator chose not to grant the optional sidecar scopes. If both includeConnections and includeFlowRuns are false, the JWT requests only tableau:flows:read plus the always-on site-settings scope.


includeFlowRuns​

When true (default), additionally returns the most recent flow runs for this flow.

Requires Tableau REST API version 3.10 (Tableau Server 2020.4) or later. On older servers, this sidecar call is skipped and a VERSION_GATE_SKIPPED warning is emitted under mcp.warnings.

When false, the tool also narrows the Tableau API scopes requested at JWT sign-in — it does not request tableau:flow_runs:read. See includeConnections above for the metadata-only deployment story.

Version gating (VERSION_GATE_SKIPPED)​

Emitted when includeFlowRuns: true but the Tableau server is older than REST API 3.10 (Tableau Server 2020.4):

{
"type": "VERSION_GATE_SKIPPED",
"severity": "WARNING",
"message": "Flow runs require Tableau REST API 3.10 or later; this server is older.",
"affectedField": "flowRuns"
}

flowRunLimit​

The maximum number of recent flow runs to return when includeFlowRuns is true. Range: 1-100. Default: 10. Runs are sorted by startedAt descending (newest first).

When the flow has more historical runs than this limit, the tool returns the most-recent slice and emits a FLOW_RUNS_TRUNCATED warning under mcp.warnings. There is no other signal in the response that distinguishes a truncated history from a complete one — always inspect mcp.warnings before reporting "complete history" to the user.

Run-history truncation (FLOW_RUNS_TRUNCATED)​

Emitted when the flow has more runs than flowRunLimit. The flowRuns array contains the most-recent slice; older runs exist but are NOT in the response.

{
"type": "FLOW_RUNS_TRUNCATED",
"severity": "WARNING",
"message": "Returned the 10 most-recent flow runs (sorted startedAt desc). The flow has additional historical runs not included in this response. To see more runs: 1. Re-call this tool with a higher `flowRunLimit` (max 100). 2. For deeper history (more than 100 runs) use the Tableau Flow Runs REST API directly with `filter=flowId:eq:<id>` and `pageNumber` pagination, or with a date-range filter (e.g. `startedAt:gt:<iso-timestamp>`).",
"affectedField": "flowRuns",
"returnedCount": 10
}

Why this warning exists. The Tableau Flow Runs endpoint (GET /sites/{site}/flows/runs) does not return a pagination block, so the tool cannot read totalAvailable to know whether the response was truncated. Instead it uses the "+1 probe" technique: request flowRunLimit + 1 rows in a single call; if more than flowRunLimit come back, the array was truncated and this warning is emitted (verified live against Tableau REST 3.30).

Recovery actions. When you see this warning:

  1. If the user wants more recent context, re-call with a higher flowRunLimit (up to 100).
  2. If the user wants deeper history (more than 100 runs, or a specific date range), this tool cannot satisfy it in v0. Recommend the user query the Tableau Flow Runs REST API directly with filter=flowId:eq:<id> and pageNumber pagination, or with a date-range filter such as startedAt:gt:2025-01-01T00:00:00Z.

Anti-patterns. Do NOT confidently report a partial run history (e.g. "this flow has run 10 times") when this warning is present — the response is a window onto a longer history, not the complete record. Daily-running production flows can easily accumulate hundreds of runs per year.

Notes and caveats​

  • Partial failure via mcp.warnings. The primary Query Flow call is atomic — if it fails, the tool returns an error. The optional connections and flowRuns sidecars are best-effort: if either fails (the user lacks permission, the server is too old, or the request times out) the tool still returns the flow's primary metadata and surfaces a structured warning under mcp.warnings instead of failing the whole call. A sidecar fetch failure is reported as a SIDECAR_FETCH_FAILED warning:
{
"type": "SIDECAR_FETCH_FAILED",
"severity": "WARNING",
"message": "Failed to fetch connections: HTTP 403 Forbidden",
"affectedField": "connections",
"httpStatus": "403"
}
  • Response-size guidance. By default this tool returns metadata + output steps + all connections

    • the 10 most-recent runs. Each sidecar adds payload, so prefer the narrowest call that answers the user's question:
    • "What is this flow?" (just metadata) — includeConnections: false, includeFlowRuns: false
    • "What does this flow read from?" — includeFlowRuns: false (keep connections)
    • "Did the latest run succeed?" (status only) — flowRunLimit: 1 (or 3)
    • "Show me the run history" — flowRunLimit: <n> up to 100

    When in doubt, prefer the lower limit — you can always re-call with a higher limit if the first response is insufficient.

  • Bounded context. When the MCP instance is restricted via INCLUDE_PROJECT_IDS or INCLUDE_TAGS, a flow outside the allowed set is rejected before any flow detail or sidecar is fetched, so get-flow cannot read a flow by id that list-flows would have filtered out.

  • No error details for Failed flow runs. The flowRuns[*].status field is available (e.g. Success, Failed, Cancelled), but the underlying job error message is not surfaced by the public Tableau REST API and is therefore not exposed here. To investigate a failure, inspect the run in the Tableau Server / Cloud UI.

  • No per-output-step run details. The flowRuns field reflects ad-hoc runs returned by the public REST API; per-output-step success/failure breakdowns and timings are not included.

  • No exact total-run count. Tableau's Flow Runs endpoint does not expose a totalAvailable field, so the tool cannot report exactly how many runs exist beyond what was returned — only whether more do, via the FLOW_RUNS_TRUNCATED warning. For deeper history queries, see the recovery actions on that warning.

Example result​

{
"id": "d00700fe-28a0-4ece-a7af-5543ddf38a82",
"name": "Sales Cleanup",
"description": "Cleans up the daily sales feed",
"webpageUrl": "https://10ax.online.tableau.com/#/site/mcp-test/flows/3",
"fileType": "tflx",
"createdAt": "2024-11-06T04:57:55Z",
"updatedAt": "2024-11-06T21:31:00Z",
"project": {
"id": "6f8a2966-e173-11e8-ae74-ffd84c19d7f3",
"name": "Default",
"description": "The default project that was automatically created by Tableau."
},
"owner": {
"id": "711e59cf-d1c0-446e-be48-3673ae067f7b",
"name": "jane.doe@example.com",
"fullName": "Jane Doe",
"email": "jane.doe@example.com",
"siteRole": "Creator"
},
"tags": { "tag": [{ "label": "sales" }] },
"outputSteps": [{ "id": "5e4c9a74-d29a-4f62-baa5-97c443440dfc", "name": "CoffeeChainOutputCSV" }],
"connections": [
{
"id": "5fd1c1db-572f-4ebd-94e7-a09e212bc147",
"type": "sqlserver",
"serverAddress": "mySQLServer",
"userName": "analyst",
"embedPassword": true
}
],
"flowRuns": [
{
"id": "a1a1a1a1-1111-1111-1111-111111111111",
"flowId": "d00700fe-28a0-4ece-a7af-5543ddf38a82",
"status": "Success",
"startedAt": "2025-04-01T10:00:00Z",
"completedAt": "2025-04-01T10:05:00Z",
"progress": 100
}
]
}
  • list-flows — list the Tableau Prep flows on a site and obtain a flowId.

Response-size guidance​

Question shapeRecommended arguments
"What is this flow?" (just metadata)includeConnections: false, includeFlowRuns: false
"What does this flow read from?"includeFlowRuns: false (keep connections)
"Did the latest run succeed?" (status only)flowRunLimit: 1 (or 3)
"Show me the run history"flowRunLimit: <n> up to 100

Partial failure (mcp.warnings)​

The primary Query Flow call is atomic; if it fails, the tool returns an error.

The optional connections and flowRuns sidecars are best-effort. If either of them fails (for example, the user lacks permission, the server is too old, or the request times out) the tool will still return the flow's primary metadata and surface a structured warning instead of failing the whole tool call. The tool can emit three warning types:

SIDECAR_FETCH_FAILED​

VERSION_GATE_SKIPPED​

Failure reasons (mcp.failureSummary)​

On Tableau REST API >= 3.30, a Failed run carries failureReason: { available, message } giving the cause of the failure. It is readable by any caller who can see the run — it comes from the flow's output-step errors, not the admin-only background job.

When at least one returned run carries a reason, the tool also emits mcp.failureSummary, which groups those failures by reported message and availability:

  • failedRunCount — Failed runs among the returned runs.
  • failedFlowCount — distinct flows with a failure. Here that is 1 (or 0 if Tableau omits flowId on the runs), since this tool returns runs for a single flow; the field exists so the shape matches List Flow Runs exactly.
  • reasons — one entry per distinct { message, available } pair, largest first, as { message, available, runCount, flowIds }. A group is not always a single root cause: several distinct underlying errors can map to the same short localized message, and the REST API does not expose the underlying error identifier.
  • available: false means Tableau could not determine the cause and message is a generic placeholder. Do not present it as a diagnosis. This tool emits no run-history deep link of its own — append /runHistory to the webpageUrl already in the response to open the flow's run history and read the error in the Tableau UI.

Because the counts cover all Failed runs while reasons covers only reason-bearing ones, sum(reasons[].runCount) can be less than failedRunCount. On servers below REST API 3.30 both failureReason and mcp.failureSummary are absent.

{
"mcp": {
"failureSummary": {
"failedRunCount": 1,
"failedFlowCount": 1,
"reasons": [
{
"message": "Table \"orders\" was not found.",
"available": true,
"runCount": 1,
"flowIds": ["d00700fe-28a0-4ece-a7af-5543ddf38a82"]
}
]
}
}
}

Limitations​

A few things this tool deliberately does not expose in the current version:

  • Failure reasons need REST API >= 3.30, and only cover Failed runs. On older servers failureReason and mcp.failureSummary are simply omitted and the response is unchanged. Even on 3.30+, there is no reason for a Cancelled run and nothing explaining why a run is slow or stuck InProgress.
  • A reason is a short message, not a log. failureReason.message is a short localized cause. The full underlying job error is not surfaced by the public Tableau REST API and reading it requires site-administrator access. To investigate further, inspect the run in the Tableau Server / Cloud UI. mcp.failureSummary's counts inherit this limit: they describe the returned runs only, so never report them as the flow's total or historical failure rate.