Skip to main content

Query Admin Insights

Queries all three Tableau Cloud Admin Insights datasources and the deterministic stale-content report through a single entry point. Dispatches on kind to one of four backends:

  • ts-events — raw VDS query against the TS Events datasource (audit events: access, publish, update, delete)
  • site-content — raw VDS query against the Site Content datasource (content metadata, ownership, sizes)
  • job-performance — raw VDS query against the Job Performance datasource (extract refresh and subscription execution history)
  • stale-content — server-side anti-join that returns already-filtered stale rows with no client-side math required. Subject to a server-side row cap (STALE_CONTENT_MAX_ROWS, default 100) — see Row cap.

The tool is admin-only — it is registered only when ADMIN_TOOLS_ENABLED=true, and at request time it verifies the caller's site role and rejects anything below SiteAdministratorCreator / SiteAdministratorExplorer / ServerAdministrator. Admin Insights datasource LUIDs are resolved automatically; callers do not pass datasourceLuid.

APIs called​

Required arguments​

kind​

Which admin-insights backend to query:

  • ts-events — raw VDS query against TS Events
  • site-content — raw VDS query against Site Content
  • job-performance — raw VDS query against Job Performance
  • stale-content — deterministic stale-content anti-join

query​

Required when kind is ts-events, site-content, or job-performance. Ignored when kind is stale-content.

A fully formed VDS query object: fields, filters, parameters. The schema mirrors the schema accepted by the query-datasource tool.

Example (TS Events — last-access per item):

{
  "kind": "ts-events",
  "query": {
    "fields": [
      { "fieldCaption": "Item Id" },
      { "fieldCaption": "Item Type" },
      { "fieldCaption": "Event Date", "function": "MAX", "fieldAlias": "last_access" }
    ],
    "filters": [
      {
        "field": { "fieldCaption": "Event Type" },
        "filterType": "SET",
        "values": ["Access"],
        "exclude": false
      }
    ]
  },
  "limit": 500
}

Optional arguments​

limit​

The maximum number of rows to return. Applied when kind is ts-events, site-content, or job-performance; ignored for stale-content.

The effective row limit is the tightest of:

  1. The tool cap (MAX_RESULT_LIMITS=query-admin-insights:N)
  2. The caller-supplied limit

See also: MAX_RESULT_LIMIT

minAgeDays​

For kind="stale-content" only. Minimum days since last access for content to be considered stale. Falls back to the server-configured STALE_CONTENT_MIN_AGE_DAYS, which defaults to 90.

Range: 1–3650.

Example: 30

projectIds​

For kind="stale-content" only. Optional list of project LUIDs to scope the report to. Resolved to project names via the REST API. Invalid or out-of-scope LUIDs are reported in mcp.warnings rather than silently dropped. If none resolve, the tool returns an empty report.

Example: ["af59ee84-a375-4cb4-84b9-eaa7864f59fb"]

itemTypes​

For kind="stale-content" only. Optional filter for item types. Defaults to ["Workbook", "Datasource"].

Example: ["Datasource"]

Row cap (stale-content)​

The stale-content backend enforces a server-side row cap to protect the destructive stale-content cleanup flow from acting on an unreviewed mass set. The cap is configured by STALE_CONTENT_MAX_ROWS (default 100, range 1–10000; overridable per-site and per-request).

When the stale-item count is at or below the cap, the full rows array is returned as usual.

When the count exceeds the cap, the tool:

  • returns an empty rows array (rows: []) — the row payload is withheld so a caller cannot act on an unreviewed batch;
  • still reports the true pre-cap totals in totalStaleItems and totalStaleSizeBytes, so a read-only report can state the magnitude;
  • appends a structured ROW_CAP_EXCEEDED warning (severity ERROR) to mcp.warnings guiding the caller to narrow scope (e.g. a specific projectIds subset or a higher minAgeDays) and re-run.

This is a successful result, not an error — only the row payload is withheld.

Notes and caveats​

  • Tableau Cloud TS Events lookback caps at 90 days by default (365 days with Advanced Management). Items beyond the lookback cannot be distinguished on last-access timestamps.
  • Field captions differ between datasources — e.g. Item Id (TS Events) vs Item ID (Site Content). Inspect with get-datasource-metadata when in doubt.
  • The stale-content backend excludes the Tableau-managed Admin Insights project by design.
  • Last Accessed At is null for never-accessed items; the stale-content backend ages those from Created At and flags them neverAccessed: true.
  • The stale-content backend caps returned rows at STALE_CONTENT_MAX_ROWS (default 100). Above the cap, rows is empty but totalStaleItems still reflects the true count and a ROW_CAP_EXCEEDED warning is attached — see Row cap.
  • This tool intentionally bypasses the standard datasource access checker because Admin Insights datasources are internal/known and admin-gated independently.

Example results​

Raw VDS query (kind: "ts-events")​

{
  "data": [
    { "Item Id": "5092107", "Item Type": "Datasource", "last_access": "2026-04-15T00:00:00Z" },
    { "Item Id": "1412202", "Item Type": "Workbook", "last_access": "2026-05-08T21:12:45Z" }
  ]
}

Stale-content report (kind: "stale-content")​

{
  "thresholdDays": 90,
  "totalStaleItems": 2,
  "totalStaleSizeBytes": 5586253,
  "rows": [
    {
      "itemId": "1412202",
      "itemType": "Workbook",
      "itemName": "World Indicators",
      "project": "Samples",
      "ownerEmail": "owner@example.com",
      "createdAt": "2025-09-02T23:26:02",
      "updatedAt": "2025-09-02T23:26:02",
      "lastUsedDate": "2025-09-02T23:26:02",
      "daysSinceLastUse": 259,
      "size": 796179,
      "neverAccessed": true
    }
  ]
}

Stale-content report above the row cap (kind: "stale-content")​

{
  "thresholdDays": 90,
  "totalStaleItems": 3376,
  "totalStaleSizeBytes": 894837291,
  "rows": [],
  "mcp": {
    "warnings": [
      {
        "type": "ROW_CAP_EXCEEDED",
        "severity": "ERROR",
        "message": "Found 3376 stale items, which exceeds the server-configured cap of 100 (STALE_CONTENT_MAX_ROWS). The row payload was withheld to prevent acting on an unreviewed mass set; totalStaleItems reflects the true count. Narrow the scope (e.g. a specific projectIds subset or a higher minAgeDays) and re-run to receive rows.",
        "totalStaleItems": 3376,
        "maxRows": 100,
        "reason": "over-row-cap"
      }
    ]
  }
}