Update Cloud Extract Refresh Task

Updates the schedule of an extract refresh task on Tableau Cloud. Use this to change how often a refresh runs (e.g. downgrade Daily → Weekly), shift its time window, or modify the day/hour it executes — without recreating the task.

:::warning Admin Only This tool is restricted to Tableau site administrators and requires the ADMIN_TOOLS_ENABLED environment variable to be enabled. :::

:::info Tableau Cloud Only This tool calls the Cloud variant of the update endpoint and is not appropriate for Tableau Server. The Server variant has a different payload shape and is tracked separately. :::

Confirm and audit

This mutation is two-phase, gated on a server-generated single-use confirmation token:

1. Preview (default — confirm omitted or false): reports the new schedule that would be applied without changing anything, and returns a single-use confirmationToken.
2. Update (confirm: true + confirmationToken): applies the schedule update. The server verifies and consumes the token first.

The token is server-generated and bound to the previewed taskId and schedule: a token minted while previewing schedule A cannot confirm an update to schedule B, and a confirm: true with no prior preview (no valid token) is rejected server-side. This gate genuinely requires the preview phase to have run for exactly this change; it cannot be bypassed by computing a value. Present the change to the user and get explicit approval before confirming.

MCP-Apps confirm panel (cooperative human-in-the-loop)

When the mcp-apps feature flag is enabled, this tool ships with an MCP App and the preview phase renders an in-iframe confirm panel describing the schedule change (new frequency and time window, plus a live countdown) instead of returning preview text the model could act on. The schedule change is then applied only when a person clicks Apply schedule change in that panel, which invokes the model-invisible confirm-update-cloud-extract-refresh-task tool (visibility: ['app']), passing the task id and the full structured schedule. With the flag on, the model-driven confirm: true path is closed — the assistant cannot apply the change on the user's behalf; the only route is the human gesture. The confirm tool verifies a fresh, single-use human approval recorded during the preview (within MUTATION_PREVIEW_TTL_MINUTES, default 5); a missing or expired approval rejects the update. When the flag is off the tool behaves exactly as the two-phase confirm/confirmationToken flow described above.

Cooperative, not server-enforced

This is cooperative human-in-the-loop: it depends on the MCP client honoring visibility: ['app'] (hiding the confirm-* tool from the model) and rendering the confirm panel. The human approval is recorded during the model-driven preview phase, so a non-cooperating client that ignores the visibility hint could still drive preview → confirm-* back-to-back with no human gesture. This task tool has no tag layer — the app approval is the only gate — so a non-cooperating client has nothing else to clear (the schedule-bound registry nonce still proves a preview ran, but not that a human approved). Server-enforced HITL (an approval primitive the model cannot forge or reach) is tracked as follow-up work (W-23125362).

Authoritative audit

Every attempt — both the preview and the confirmed update, and both allowed and denied attempts (for example a non-admin caller) — emits a structured authoritative audit record to the server's durable log sink (logger audit, level notice), not just to the tool-response text. Each record captures the actor identity, the tool, action (update), phase, the target id, the confirmation evidence kind (registry-nonce for this tool), and the result. A confirmed update emits an allowed record when authorized, then a terminal completed (or failed, with failureDetail) record reflecting the REST outcome — so the trail records what actually happened, not just intent. This routing is centralized in the shared mutation guard so every TMCP mutation tool audits identically.

APIs called

• Update Cloud Extract Refresh Task

Use cases

Use this tool when you need to:

• Reduce the frequency of an under-used extract refresh (e.g. Hourly → Daily, Daily → Weekly)
• Move a refresh window to off-peak hours
• Change the recurrence intervals (e.g. weekday → weekend)

Required permissions

• Tableau Cloud: Requires tableau:tasks:write OAuth scope
• Site Role: Must be one of:
  • SiteAdministratorCreator
  • SiteAdministratorExplorer
  • ServerAdministrator

Configuration

Enable this tool by setting:

ADMIN_TOOLS_ENABLED=true

See also: Environment Variables

Arguments

Parameter	Type	Required	Description
taskId	string (UUID)	Yes	The ID of the extract refresh task to update. Obtain from list-extract-refresh-tasks.
confirm	boolean	No	Set true to apply the update (requires confirmationToken). When omitted or false, previews the change without applying it.
confirmationToken	string	No	The single-use token returned by a prior preview of this same taskId and schedule. Required when confirm is true; ignored otherwise. A token minted for a different schedule will not validate.
schedule	object	Yes	The new schedule to apply. Replaces the existing schedule wholesale.

schedule shape

Field	Type	Required	Description
frequency	enum	Yes	One of Hourly, Daily, Weekly, Monthly.
frequencyDetails.start	string	Yes	Start time in 24-hour HH:mm:ss format, e.g. "06:00:00".
frequencyDetails.end	string	Hourly only	End time in 24-hour HH:mm:ss format. Required for Hourly (minute portion must match start, must be strictly after start). Omit for Daily/Weekly/Monthly — Tableau ignores it.
frequencyDetails.intervals.interval	array	No	Recurrence intervals. Each entry can specify weekDay (Sunday..Saturday), monthDay, hours, or minutes depending on the frequency.

Schedule constraints

The schema enforces these rules — invalid input is rejected before any Tableau API call:

• Time format – start and end must be zero-padded HH:mm:ss (e.g. "06:00:00", not "6:00:00").
• Minute boundary – The minute portion of start (and end, when present) must be on a 5-minute boundary: 00, 05, 10, 15, 20, 25, 30, 35, 40, 45, 50, or 55, with seconds = 00. 07:26:00 is rejected; 07:25:00 and 07:30:00 are accepted.
• Hourly – start and end must share the same minute portion (e.g. 06:00:00/18:00:00 ✓, 06:00:00/18:30:00 ✗); end must be strictly after start (numeric comparison, not lexical).
• Daily / Weekly / Monthly – end is ignored — omit it.
• Hourly and Daily require at least one interval with weekDay (Tableau rejects them otherwise with 409004).
• Weekly requires at least one interval with weekDay; Monthly requires at least one interval with monthDay.

Tableau may still reject a schema-valid request with 409004 Conflict (Invalid subscription schedule) for site-specific rules. In that case the tool surfaces Tableau's structured error verbatim — e.g. Tableau 409 [409004]: Conflict: Invalid subscription schedule. (...) — so callers can recover without parsing axios errors. A 404 is mapped to a "Tableau Cloud only" hint pointing at list-extract-refresh-tasks since the most common cause is calling against a Tableau Server site or with a stale taskId.

Example: Daily → Weekly Sunday at 06:00

{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schedule": {
    "frequency": "Weekly",
    "frequencyDetails": {
      "start": "06:00:00",
      "intervals": { "interval": [{ "weekDay": "Sunday" }] }
    }
  }
}

Example: Hourly between 08:00 and 18:00 every 2 hours, Mondays

{
  "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "schedule": {
    "frequency": "Hourly",
    "frequencyDetails": {
      "start": "08:00:00",
      "end": "18:00:00",
      "intervals": { "interval": [{ "hours": 2 }, { "weekDay": "Monday" }] }
    }
  }
}

Response

A confirmation message describing the updated task and its new schedule:

Extract refresh task 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' has been successfully updated. New schedule: Weekly (start 06:00:00).

Error cases

Scenario	Behavior
Task ID does not exist	Returns a 404 error
User is not a site administrator	Returns an error indicating admin permissions are required
ADMIN_TOOLS_ENABLED not set	Tool is not registered and unavailable to the client
Invalid frequency value	Schema-level rejection before any API call
Missing frequencyDetails.start	Schema-level rejection before any API call
Tableau Server (not Cloud)	This tool is Cloud-only; calling it against a Server site is not supported