Review Report

Reviewing Power BI Reports

Structured evaluation of Power BI reports to produce actionable feedback for developers and consultants. A report review assesses whether a report is effective, well-built, and actually being used. The output is a prioritized list of findings with concrete recommendations.

Note that the skill works on one of three scenarios:

1. Report under development: In this scenario, the focus is more on the report content, structure, organization, and performance based on accurately gathered requirements. 2. Report in testing: In this scenario, the focus might incorporate user feedback or check basic information about the deployed report in Power BI / Fabric. 3. Report in use: This is the ideal scenario, where the focus is usage; the ultimate definition of success is whether the report is being used; what percentage of the people who have access to the report have accessed it in the last 28 days, and how much? Bad reports aren't used, or have declining usage.

In scenario 2-3 you may still provide feedback on the report content / structure, but prioritizing other things first.

When to Use

Activate when conducting a report review, audit, or health check. Common triggers:

• Reviewing report quality before a release or handoff
• Assessing whether existing reports are worth maintaining
• Identifying optimization opportunities across a workspace
• Evaluating report design and data presentation effectiveness
• Investigating report performance issues

Review Dimensions

A comprehensive report review evaluates six dimensions. Not every review needs all six -- scope to what the user needs.

1. Usage and Adoption

The most objective signal of report value. A report that nobody views is a maintenance liability regardless of its design quality.

Retrieve usage data with the scripts in scripts/:

# Workspace overview (views, rank, page views, load times)
python3 scripts/get_report_usage.py -w <workspace-id>

# Add Tier 3 cross-workspace last-visited timestamps via the undocumented DataHub V2 API
# Useful for the "is this report being used at all" question without tenant admin role
python3 scripts/get_report_usage.py -w <workspace-id> --include-datahub

# Single report deep-dive (daily views, per-viewer breakdown, page views by day)
python3 scripts/get_report_detail.py -w <workspace-id> -r <report-id>

# Distribution audit (who has access, through what channels)
python3 scripts/get_report_distribution.py -w <workspace-id> -r <report-id>

Filtering viewers: Exclude non-consumer users from adoption metrics. Service principals (type App), report developers, and IT / support personnel inflate viewer counts and distort reach. See references/usage-metrics.md for identification heuristics and references/distribution.md for resolving security groups and distribution lists via the Microsoft Graph API.

Evaluate usage signals:

• Audience reach is the most important metric: what percentage of users with access have actually viewed the report in the last 7, 28, and 60 days? See references/distribution.md for how to calculate reach and what the numbers mean
• View trends: Is viewership stable, growing, or declining? Use the rolling 7D average (see references/usage-metrics.md)
• Page view distribution: Are views concentrated on one page or spread across the report? Before calling a page unused, check whether it is a tooltip/drillthrough target (no direct views expected) and confirm reachability via pbir pages list
• Last visited: When was the report last accessed by anyone? Tier 1 (Admin Activity Events, 30-day rolling, admin role required) is the official path. The Tier 3 DataHub V2 lastVisitedTimeUTC field (--include-datahub) is the non-admin cross-workspace fallback; flag to the user it's undocumented and can break
• Load times: Are P50 and P90 load times acceptable for the audience? See references/performance.md for interpretation

Do not use arbitrary thresholds for what constitutes "healthy" or "concerning"; these depend entirely on the report's audience, purpose, and lifecycle stage. A report for 3 analysts has different expectations than one for 300 executives. Match the review window to the report's cadence before drawing conclusions; see references/usage-interpretation.md for common misreads of the modern Usage Metrics report and the retire/keep/redesign decision framework.

Subscriptions are not views. Email subscriptions deliver report snapshots without generating view events. Check admin/reports/{id}/subscriptions (requires Fabric Admin) for active subscribers. A report with 0 views but active subscriptions is being consumed passively.

Use rolling 7-day averages for view trends. Raw daily counts are noisy. Compare the current 7D average to the prior 7D to identify trajectory. See references/usage-metrics.md for methodology.

Key insight: Reports with 0 views are not necessarily bad. They may be new, seasonal, consumed via subscriptions, or used via embedded scenarios not captured in telemetry. Cross-reference with last-visited timestamps. Prefer the Tier 1 admin Activity Events feed where admin access is available; fall back to the Tier 3 DataHub V2 path when it is not, while flagging that it is undocumented.

Permissions: Tier 1 (WABI) needs any workspace role. Tier 2 (model) needs workspace Contributor+. Distribution and subscription checks need Fabric Admin (tenant-level). See references/usage-metrics.md for the full permission matrix.

For additional context on the usage metrics dataset schema and available tables, see usage-metrics-dataset/.

2. Design and Layout

Evaluate the visual design and information architecture. Consult the pbi-report-design skill for detailed guidelines. Reference: Data Goblins Report Checklist.

Checklist:

• [ ] Page titles present and descriptive
• [ ] Visual spacing consistent (equal gaps between visuals and margins)
• [ ] Detail gradient followed (KPIs top-left, detail bottom-right)
• [ ] Color usage intentional and accessible (no gratuitous color, no red/green for colorblind users)
• [ ] Font family, size, and formatting consistent throughout
• [ ] Visual count reasonable (loosely 12-15 max per page, depends on complexity)
• [ ] No empty visuals (all visuals have field bindings)
• [ ] Theme applied (not default Power BI theme)
• [ ] Chart axes begin at zero (unless intentional)
• [ ] Default sort configured on all visuals
• [ ] Visual objects labelled clearly in the selection pane (grouped with descriptive names)
• [ ] Mobile layout provided if relevant audience
• [ ] Visual headers configured (disable when drill-down/through not needed)
• [ ] Interactions configured (cross-filtering/highlighting intentional, not default)
• [ ] Slicer 'Apply' buttons considered for performance-sensitive pages
• [ ] Synchronized slicers where required across pages

3. Data Model Binding

Evaluate the connection between the report and its underlying semantic model.

Checklist:

• [ ] Report connects to a published semantic model ("thin report") rather than embedding its own ("thick report")
• [ ] All field bindings resolve to existing model columns/measures
• [ ] Extension measures (thin report measures) used sparingly and only for report-specific logic
• [ ] No broken or orphaned field references
• [ ] Appropriate use of measures vs. columns in visuals (aggregation context)
• [ ] Separate filters are not active on visual-level

4. Performance

Assess report load time and visual complexity. Run the performance audit script:

python3 scripts/performance_audit.py -w <workspace-id> -r <report-id>

See references/performance.md for percentile interpretation, DAX query inference from visual field bindings, and common anti-patterns.

Key indicators: P50 and P90 load times, visual count per page, extension measure count. Visual count is a proxy; query cost per visual is the real driver. See references/performance-audit.md for the full cost model, how to interpret a Performance Analyzer export, DirectQuery report-layer tuning levers, and the interaction/navigation audit. Do not apply rigid visual-count thresholds without reading the cost model first.

5. Report Metadata and Governance

Assess the report's governance posture. See references/report-metadata.md.

Checklist:

• [ ] Thin report (connected to published model, not embedded thick model)
• [ ] Endorsement status appropriate for its audience (Certified for production, Promoted for team use)
• [ ] Sensitivity label applied if tenant policy requires it
• [ ] Part of a deployment pipeline if in a production workspace
• [ ] Distribution via workspace app or org app (not direct links or publish-to-web)
• [ ] Access granted via security groups, not individual users
• [ ] View-only access for consumers (Viewer role), edit access only for developers
• [ ] Export-to-Excel patterns reviewed for data governance risks (see references/export-to-excel.md)

6. Accessibility, Standards, and Documentation

Evaluate whether the report meets accessibility, organizational standards, and documentation requirements.

Accessibility:

Most accessibility checks can be run statically against PBIR files; only focus traversal and screen-reader readout need a live report. See references/accessibility-audit.md for the full procedure: geometry/alignment audit, tab-order reconciliation, static pass (alt text, decorative items, color-only encoding), SVG-measure checks, script visual checks, and mobile readiness.

Summary checklist:

• [ ] Alt text present on all data visuals (including SVG-measure hosts and script visuals)
• [ ] Decorative items removed from tab sequence (tabOrder = -1)
• [ ] Tab order matches geometric reading pattern (top-to-bottom, left-to-right)
• [ ] No color-only encoding (paired with shape, glyph, or text)
• [ ] Color contrast meets WCAG 2.1 AA (4.5:1 text, 3:1 UI elements)
• [ ] Font sizes legible (min 9pt data, 12pt labels)
• [ ] Mobile layout present on consumption-intended pages
• [ ] Live keyboard Tab traversal verified (cannot be confirmed from files)

Standards:

• [ ] Sensitivity labels applied if required by governance policy
• [ ] Naming conventions followed (report name, page names, visual titles)
• [ ] Link provided for users to report issues or submit feedback
• [ ] Filter combinations tested thoroughly

Documentation (for handover/production):

• [ ] Purpose statement: what business questions does the report answer?
• [ ] Intended audience and user segments identified
• [ ] Atypical features documented (visual-level filters, hidden slicers, bookmarks, custom visuals)
• [ ] Support personnel and procedures identified
• [ ] Training/adoption materials available for business users

Review Workflow

Step 1: Scope

Clarify what the user wants reviewed. Ask:

• Single report or workspace-wide audit?
• Which dimensions matter most? (usage, design, performance, all?)
• Is there a specific concern prompting the review?
• Where should findings be documented? (scratchpad, agent-docs, obsidian notebook, wiki, etc.)

Step 1a: Determine Scope and Access

Ask the user:

• Do they have access to the underlying semantic model?
• Are they the developer of both the report and model, or only one?

If the semantic model is in scope, use the semantic-model skill in parallel. Many report issues (slow visuals, (Blank) values, missing fields) originate in the model. See references/best-practices.md for model symptoms that surface in reports.

Step 1b: Determine Report Lifecycle Stage

If the report is local-only or not yet published, ask the user:

"Is this a report in development which doesn't yet have users, a report in testing with a subset of the user audience, or a report that's already distributed and should be seeing active usage and value generation?"

This determines which dimensions are applicable:

Remind the user: a report's success lives and dies on whether it is being used and delivering business value. Design, performance, and structure can be reviewed proactively, but usage data is the only objective measure of whether the report is working. Good requirements gathering helps achieve adoption, but it can never be guaranteed.

If the report is local-only, ask where the published version is (or will be). Usage metrics require a published report in the Power BI service.

Step 2: Gather Data

Run the usage script for quantitative data. Export or inspect the report definition for qualitative assessment.

Step 3: Evaluate

Walk through each relevant dimension using the checklists above. Score each finding by severity:

• Critical: Broken functionality, security risk, or completely unused report consuming capacity
• High: Performance issues impacting users, major design violations, missing data bindings
• Medium: Design inconsistencies, moderate performance concerns, partial accessibility gaps
• Low: Minor polish items, style preferences, optimization opportunities

Step 4: Report Findings

Present findings as a structured summary. Lead with the most impactful findings.

Format:

REPORT REVIEW: <Report Name>
===============================

USAGE SIGNAL
  Views (30d): 47  |  Viewers: 8  |  Rank: #3/22
  Top pages: Overview (60%), Detail (30%), Trends (10%)
  Load time P50: 3.2s  |  P90: 7.1s

CRITICAL
  - [Performance] P90 load time exceeds 7s due to 14 visuals on Overview page

HIGH
  - [Design] No page titles on 2 of 3 pages
  - [Binding] 3 visuals have broken field references

MEDIUM
  - [Design] Inconsistent margins (24px left, 32px right)
  - [Accessibility] Missing alt text on 5 data visuals

LOW
  - [Design] Default theme applied; consider custom theme
  - [Standards] Report name uses spaces instead of hyphens

Prerequisites

Before running usage scripts, ensure:

- Azure CLI authenticated: run az login if needed

- fab CLI authenticated: run fab auth login if needed (for distribution script)

- Python requests package: uv pip install requests

References

• `references/usage-metrics.md` -- Full documentation of all usage data APIs (official and undocumented)
• `references/usage-interpretation.md` -- Reading modern Usage Metrics correctly; retire/keep/redesign decision framework
• `references/distribution.md` -- All report access paths and how to audit them
• `scripts/get_report_usage.py` -- Workspace-level usage overview
• `scripts/get_report_detail.py` -- Single report deep-dive (daily, per-viewer, per-page)
• `scripts/get_report_distribution.py` -- Distribution audit (ACL, apps, publish-to-web)
• `scripts/performance_audit.py` -- Load times + visual complexity analysis
• `references/performance.md` -- Percentile interpretation, DAX query inference from visual metadata
• `references/performance-audit.md` -- Query cost model, Performance Analyzer export, DirectQuery tuning, interaction/navigation audit
• `references/accessibility-audit.md` -- Alignment/tab-order audit, static accessibility pass, SVG/script/mobile checks
• `references/report-metadata.md` -- Thick/thin, endorsement, sensitivity, pipeline, model properties
• `references/export-to-excel.md` -- Export activity analysis, data governance implications
• `references/best-practices.md` -- Data visualization principles, chart selection, color, interaction design
• `usage-metrics-dataset/` -- Exported Usage Metrics dataset (TMDL schema + report definition)

Related Skills

• `semantic-model` -- Companion skill for semantic model design and review (run in parallel when model is in scope)
• `pbi-report-design` -- Detailed report design guidelines and layout rules
• `modifying-theme-json` -- Theme authoring, compliance auditing, formatting promotion
• `deneb-visuals`, `python-visuals`, `r-visuals`, `svg-visuals` -- Visual-specific review criteria (now in the custom-visuals plugin; add with claude plugin install custom-visuals@power-bi-agentic-development)

Accessibility Audit

File-level checks that can be run from the terminal, plus a short residue pass that requires a live report. Keep the two sets separate; never assert "passes accessibility" from a file scan alone.

Alignment and Gutter Consistency

A pure-geometry audit from the PBIR position blocks; run before any screenshot.

pbir visuals properties "Sales.Report/Overview.Page/*" -s position --json

Build four sorted lists from the output: left x, right x+width, top y, bottom y+height. Any cluster of near-but-not-identical values is a misalignment candidate; snap to the modal value. Compute gutters as gaps between a row's right edges and the next left edge; flag rows where the spread exceeds a couple of pixels. Verify that distinct x-edges on row 1 match row 2 (continuous vertical lines).

Round survivors to the grid unit with pbir set <path>.position.x <value>, then re-validate.

Notes:

• basicShape, decorative image/textbox, and actionButton participate in the grid for alignment checks but should be excluded from visual-density counts
• A visualGroup child's position is relative to the group, which has its own position + ScaleMode; resolve group offsets before comparing or you get phantom misalignment
• Geometry alignment is necessary but not sufficient; pair with the tab-order check below

Tab Order vs Reading Pattern

Spatial reading order (F/Z) and tabOrder (keyboard-tab and screen-reader announce sequence) are set independently; Power BI does not derive one from the other. A flawless Z-pattern can still ship a scrambled announced order.

pbir visuals properties "Sales.Report/Overview.Page/*" -s tabOrder --json

Reconstruct intended order from geometry: sort by (y_band, x) where y_band buckets visuals into rows. Where a visual's tabOrder rank diverges from its geometric rank, the announced order fights the layout; flag it.

Key conventions:

• A negative tabOrder (e.g. -1) removes an item from the tab sequence; Desktop writes this via the Selection pane. A meaningful visual with a negative value becomes unreachable by keyboard; flag unexpected negatives
• Decorative visuals should be removed from the tab sequence (tabOrder = -1); a decorative item still in sequence is a 1.3.2 risk
• Zero tabOrder set on every visual means the author never made the order intentional; that is a 1.3.2 risk, not a hard failure
• position.z (stacking order) is unrelated to tabOrder; never use z to fix the reading sequence
• Grouped visuals announce within their group

Static Accessibility Pass

The following checks produce findings from visual.json alone:

• Missing alt text: each data visual (exclude basicShape, decorative image/textbox, actionButton) must have non-empty general.altText; find gaps with pbir visuals format "MyPage/*" -p general.altText
• Decorative items in tab sequence: any basicShape, brand image, or divider with tabOrder >= 0 should be -1
• Tab-order coherence: dump (name, visualType, x, y, tabOrder); flag where ascending tabOrder does not track top-to-bottom, left-to-right
• Color-only encoding: a series/CF color with no paired data label, icon, or marker shape (WCAG 1.4.1)
• Unreachable meaningful visual: any data visual with a negative tabOrder

Tag each finding [Accessibility] with its WCAG SC: 1.1.1 alt, 1.3.2/2.4.3 reading/focus, 1.4.1 color-only, 2.1.1 keyboard.

SVG-Driven Visuals

Detect SVG measures by grepping reportExtensions.json expressions for image/svg+xml. Three checks not covered by the standard accessibility pass:

• Each table/matrix/card/image whose bound measure returns an svg+xml URI must have non-empty general.altText (static or measure-driven) AND the SVG-encoded numbers must also appear as a readable adjacent column. Severity high for primary KPIs, medium for decorative micro-charts
• Flag SVG measures whose only context-varying element is a fill/stroke color with no accompanying shape, glyph, or text run (color-only encoding inside the SVG)
• Flag SVG measures that recompute base aggregations inside the string-builder (CONCATENATEX over fact rows rather than pre-aggregated values), and matrix value-axis SVGs lacking a HASONEVALUE/ISINSCOPE total guard (these are both an accessibility concern and a performance one)

The Desktop Bridge screenshot does not confirm accessibility; alt text is invisible in a screenshot.

Script Visuals (Python/R)

pythonVisual and scriptVisual have additional accessibility exposure because they render a static PNG with no data table fallback and no per-cell alt text slot.

pbir visuals query --type pythonVisual --json
pbir visuals query --type scriptVisual --json

For each script visual found:

• Confirm the host visual has non-empty general.altText
• Flag the Publish to web distribution path: Python/R visuals render empty there; this is a blocking finding for public embeds
• Flag the app-owns-data embed path: R/Python visuals do not render in app-owns-data scenarios (not a future risk; broken now)
• Note the "Show visuals as tables" fallback (Ctrl+Shift+F11) does not include script visuals; the PNG is the only output

Also audit the script literal:

pbir get 'Page/MyScriptVisual.Visual' objects.script

An unreviewed third-party script is a security finding.

Mobile Readiness

A page can be flawless on web and unusable in portrait. These are entirely file-based signals:

• Has a phone layout: count mobile.json files under the page's visuals/; zero means the page falls back to rotated landscape on phones. Flag consumption-intended pages with none
• Coverage vs over-stuffing: ratio of mobile-placed to total visuals; near-zero on a key page is a gap, near-1.0 is the over-faithful-miniature anti-pattern
• Stale placement: a visual.json edited long after its mobile.json (heuristic; flag for manual review)
• Orphan records: a mobile.json whose sibling visual.json is gone (a blocking state; pbir validate catches it)
• Mobile-only override sprawl: large objects blocks in mobile.json that duplicate rather than delta desktop formatting

Tie severity to intent: a back-of-house detail page with no phone layout is fine; a headline KPI page visible in an org app is high severity. Mobile-optimized views render only in the native iOS/Android apps; a browser always shows the landscape layout, so you cannot verify portrait by browser screenshot.

Must-Render Residue

These cannot be confirmed from files; state them as not-file-verifiable:

• Tab/Shift+Tab focus traversal between regions (Ctrl+F6)
• Screen-reader readout via "Show data" (Alt+Shift+F11) and "Show visuals as tables" (Ctrl+Shift+F11)
• card/slicer/smart-narrative/Q&A/Key-Influencers/paginated are excluded from "Show visuals as tables"; the table fallback does not cover them

Screenshots do not capture focus; the only check for traversal is a live keyboard pass.

Report Design Best Practices

Data visualization and report design principles for evaluating Power BI reports. Based on the Data Goblins Report Checklist.

Reviewing Philosophy

An LLM or agent cannot assert that a report "looks good" or "is good." Provide evaluation and suggestions for possible improvements, but aim to spar with the user... steer them in the right direction and augment them with the appropriate skills to make good things.

Best practices are defaults, not mandates. They are recognized standards providing a helpful starting point for most scenarios. They are not optimizations. Optimizations are situation-specific techniques. When flagging deviations from best practices, present them as observations and suggestions, not failures. Ask the user whether the deviation is intentional. Do not over-extrapolate from one scenario to another or make assumptions about the audience or purpose of the report.

For performance recommendations specifically: do not recommend optimizations without evidence. If suggesting a change, recommend that the user test it rigorously, or offer to test it yourself by inferring queries from visual fields and querying the semantic model with a trace. Test multiple times when comparing; a single test yields misleading conclusions. Revert to simpler approaches if testing shows no meaningful improvement... avoid unnecessary complexity

When viewing a report (via Chrome MCP, Playwright, devtools, or screenshot), keep a keen eye for anomalies like (Blank) values, repeating values, or query errors, but do not use a simple screenshot or interaction to assert design competence. Always confirm font size readability with the user -- Claude tends to underestimate whether fonts are large enough.

Understanding Business Context

Before evaluating design, understand the report's purpose:

1. What business process is being reported on? Read the report definition and the definition of its underlying semantic model to understand this. 2. What questions is it trying to answer? Is it descriptive, exploratory, or prescriptive? 3. Who is the intended audience? What are they expected to do with this data? Ask the user. 4. Is the report redundant? Are there other, related reports tackling similar questions or reporting similar data? Check with the fabric-cli skill. 5. Is it replacing an existing solution? If migrating from another tool/platform, is that existing solution being used? Ask the user.

You can hypothesize, but don't assume purpose from the visual layout or metadata alone.

The 3/30/300 Rule

Layout

• Charts should be consistent in their sizes
• Equal spacing between charts on a page and between charts and the page edges
• Most important and simplest information in the top-left; more detailed/dense information in the bottom-right
• Charts should have sufficient space to render, while not too many charts are displayed at once
• Only 2-3 simple slicers on the page; the rest should be in the filter pane
• Report pages should have a clear and descriptive title
• Include data freshness information (e.g. a card showing last refresh datetime)
• Identical slicers on different pages should be synchronized

Chart Selection

Match the visualization type to the analytical question being asked.

Visual Vocabulary

Charting Best Practices

• Visuals should provide sufficient meaning and context to be interpretable and should leverage pre-attentive attributes
• Axes should start at 0 except for line charts focused on overall trend. If a line chart does not start at 0, note this in the subtitle
• Horizontal bars are better than vertical bars in most cases since axis labels are more readable
• Avoid pie and donut charts. If the user wants one, suggest a donut with smaller radius slices
• Tables and matrices should not have too many columns or try to show too much at once. Sufficient padding (4 is usually enough), not too much conditional formatting. Values should have sufficient rounding to avoid showing too much detail, but users may prefer full unformatted numbers
• Visuals should have sort order applied: typically descending by the key value field, ascending if negative numbers require more attention, or categorical for date fields (quarter, month, year, workdays MTD, etc.)
• Data labels: Use instead of axis ticks if feasible for bar charts. If data labels are shown, the axis may not be needed (but keep the axis title for context)

Anti-Patterns

• Pie charts with >5 slices: Comparing categories is better done with a simple bar chart or alternative chart type
• Dual-axis charts: Misleading when scales differ; use small multiples or separate visuals instead
• Gauges: Take up space, show one value poorly; use a card with trend instead
• Default visual interactions: Avoid deviating from default interactions unless there's an explicit reason to do so
• Too many custom/macgyvered visuals: SVG, R, Python, or heavily customized core visuals using atypical properties to achieve unique results increase maintenance burden disproportionately

Formatting and Conditional Formatting

• Formatting should not be decoration; aim for an optimally high information-to-ink ratio
• Formatting should be functional and consistent between visuals, pages, and related reports. This should be reflected in a good, common theme reused across reports
• Formatting is more about what to take away than what to add
• Static formatting should ideally be in the theme, not in bespoke visual overrides. When the theme changes, it should propagate to all downstream visuals. Some visual overrides are inevitable and necessary, but the theme should carry the baseline
• If data labels are shown, the axis may not be needed -- but keep the axis title so it's clear what is being measured

Color Usage

Color is a data encoding channel, not decoration. It must be used as a resource to steer or direct attention to important or actionable areas.

Principles

1. Muted/pastel palettes: Soft, desaturated colors reduce visual noise. Reserve saturated/bright colors for emphasis and alerts 2. Intentional encoding: Every color should mean something. Color should draw attention to important and actionable elements; it should not be overused 3. Semantic consistency: If "Sales" measures are blue on one page, it must be blue on every page 4. Sentiment colors: Reds/oranges/yellows for bad and green/blue for good should not be used for categories -- only for sentiment encoding 5. Accessible palettes: Test for red-green colorblindness. Prefer blue-orange or blue-red diverging scales. Do not rely on color alone 6. Limit the palette: 5-7 colors maximum

Font and Text

• Font family: Use Segoe UI or Segoe UI Semibold, or other default fonts built-in to Power BI. Custom fonts are not guaranteed to render on all devices
• Consistency: Font family, size, weight, and color should be consistent throughout. Variation should signal hierarchy, not randomness
• Minimum sizes: 9pt for data values, 12pt for labels and titles. Confirm with the user whether sizes are large enough -- always check this
• Data labels: Use sparingly. Dense data labels create clutter

Container Formatting

• Containers should have basic, simple formatting unless there is a specific reason to deviate
• Charts can have titles but avoid redundancy or titles/subtitles taking up too much space

Interaction Design

Slicers and Filters

• Maximum of 2-3 slicers on the page; the rest should be in the filter pane
• Apply buttons: Consider enabling on reports with performance issues
• Synchronize slicers across pages to prevent conflicting filter states
• Visual-level filters are invisible to users and a common source of confusion. Document them explicitly. Prefer page-level or report-level filters
• Default slicer selections: Set sensible defaults so the report loads with useful data

Cross-Filtering and Interactions

• Set/modified interactions can be useful but are generally avoided to prevent confusion with users and other developers
• Test filter combinations beyond the defaults and most common scenarios
• Try to interact with the report to verify cross-filtering works as expected

Navigation and Organization

• Title/landing page: Establish context before data
• Bookmarks: Use minimally. Sometimes necessary for dynamically showing/hiding charts or navigation, but generally better to avoid. Bookmark states are fragile
• Organizational pages: Provide FAQ information about the report, data, model, where to get help, how to read certain charts, calculations, etc. If not a full page, a (?) button with a link can serve the same purpose

Organizational Best Practices

• Extension measures: Can exist but should only contain logic specific to this report. If beneficial for multiple reports, push it into the semantic model
• Visual calculations: Can exist but should only contain logic specific to a single visual. If beneficial for multiple visuals, move to an extension measure or model measure
• Alt text: Good practice but very rare in practice
• Hidden visuals / hidden slicers: Can cause confusion with users and other developers, especially hidden slicers

Semantic Model Considerations

Many report issues originate in the underlying semantic model. Ask the user:

1. Do they have access to the underlying semantic model? 2. Are they the developer of both the report and model, or only one of them?

If the model is in scope, use the semantic-model skill in parallel. The following are model-related issues that surface as report symptoms:

• (Blank) values from referential integrity violations (missing keys) or incorrect relationships
• Repeating/inflated values from many-to-many or bidirectional relationships
• Slow visuals caused by expensive DAX measures, large model size, or missing aggregations
• Missing fields referenced by visual bindings (renamed or removed columns/measures)
• RLS not behaving correctly for different user contexts
• Refresh frequency not matching business needs
• Unused columns/tables inflating model size

These are documented in detail in the semantic-model skill. For the report review, note these as symptoms and flag them for model-level investigation.

Design for Agents

• Use annotations to provide documentation or descriptive instructions about reports, pages, or visuals
• Include instruction or memory files in the .Report folder that pertain to the report
• Focus on providing key learnings for next time or implicit information from the business or the analysts perspective

Report Distribution and Access Paths

Reference for all the ways a user can gain access to a Power BI report, how to check each path programmatically, and best practices for distribution.

Distribution Best Practices

Preferred Distribution Channels

Use Security Groups

Distribute access via Entra ID (Azure AD) security groups rather than individual users:

• Central management: IT or data team manages group membership in one place
• Scalability: Adding/removing users doesn't require touching Power BI
• Auditability: Group membership is logged in Entra ID
• Consistency: Same group can grant access across workspaces, apps, and reports

When reviewing a report's distribution, flag individual user assignments and recommend consolidation into security groups.

View vs Edit Access

Surface the distinction between view-only and edit-capable users:

When presenting distribution findings, separate view-only users from edit-capable users. A report with 50 viewers and 15 editors warrants investigation -- most consumers should have view-only access.

Access Paths

A user can access a Power BI report through six distinct channels. A comprehensive distribution audit checks all of them.

Permission note: Endpoints prefixed with admin/ require the Fabric Admin role (tenant-level). Endpoints under groups/{wsId}/ require at minimum a workspace Admin role. See references/usage-metrics.md for the full permission matrix.

1. Workspace Role

The most common access path. Users assigned to the workspace inherit access to all items within it.

Check via API:

fab api -A powerbi "groups/{workspaceId}/users"

Response fields: emailAddress, displayName, groupUserAccessRight, principalType (User, App, Group)

Note: Security groups appear as a single entry with principalType: Group. The API does not expand group membership. To enumerate individual users within a group, the Microsoft Graph API is required.

2. Direct Report Sharing

Reports can be shared directly with specific users, granting access without workspace membership.

Check via API (admin):

fab api -A powerbi "admin/reports/{reportId}/users"

Response fields: emailAddress, reportUserAccessRight (Owner, ReadWrite, Read, ReadReshare), principalType

Non-admin alternative:

fab api -A powerbi "groups/{workspaceId}/reports/{reportId}/users"

This returns users visible to the caller but may miss some if the caller lacks admin rights.

3. Workspace App (Power BI)

Reports can be packaged into an App and distributed to a broader audience. App users gain access to the report without workspace membership or direct sharing.

Check if workspace has an app:

fab api -A powerbi "admin/apps"
# Filter by workspaceId to find apps for the workspace

Get app users:

fab api -A powerbi "admin/apps/{appId}/users"

Response fields: emailAddress, appUserAccessRight, principalType

Note: A workspace app can have multiple audiences with different content visibility. The API returns all users but does not indicate which audience they belong to.

4. Org App

Organizational apps are distributed through the admin portal and installed by users or auto-installed via admin settings.

Check via API:

fab api -A powerbi "admin/apps"
# Look for apps with the workspace's reports

Org apps use the same API as regular apps. The distinction is in how the app is distributed (admin-installed vs user-published).

5. Publish-to-Web (Public Embed)

Publish-to-web creates a public, unauthenticated URL for the report. Anyone with the link can view the report. This is a significant security risk for reports containing internal data.

Check via API (Fabric Admin):

fab api -A powerbi "admin/widelySharedArtifacts/publishedToWeb"

Response fields: artifactId, displayName, artifactType, shareType (PublishToWeb), sharer.emailAddress

Filter the response by artifactId matching the report's GUID.

Quick check for a specific report using fab CLI:

# Check if a specific report has active publish-to-web links
fab api -A powerbi "admin/widelySharedArtifacts/publishedToWeb" \
  -q "ArtifactAccessEntities[?artifactId=='<report-id>']"

If the result is non-empty, the report is publicly accessible. Flag this as a critical finding in any review unless the report is intentionally public-facing.

Revoking publish-to-web: Cannot be done via API. Direct the workspace admin or Fabric admin to revoke via the Power BI admin portal under "Embed codes".

6. Org-Wide Sharing Links

Reports can be shared with a link that is accessible to everyone in the organization.

Check via API (admin):

fab api -A powerbi "admin/widelySharedArtifacts/linksSharedToWholeOrganization"

Response fields: Same as publish-to-web. Filter by artifactId.

Resolving Security Groups and Distribution Lists

The Power BI APIs return security groups and distribution lists as a single entry with principalType: Group. The API does not expand group membership. This means a workspace shared with Sales-Team@contoso.com appears as one entry, but may represent 50 users.

Expanding Group Membership

To enumerate individual users within a group, use the Microsoft Graph API:

# Get group members by group display name (requires Graph permissions)
# First, find the group's object ID
fab api -A azure "https://graph.microsoft.com/v1.0/groups?\$filter=displayName eq 'Sales-Team'"

# Then enumerate members
fab api -A azure "https://graph.microsoft.com/v1.0/groups/{groupId}/members"

Required permissions: GroupMember.Read.All or Group.Read.All (delegated or application).

If Graph API access is unavailable, note the group names in the audit and flag that the actual audience size is unknown. Ask the user or an admin to provide group membership counts.

Nested Groups

Groups can contain other groups. The /members endpoint returns direct members only. To fully resolve nested groups:

# Transitive members (recursively expands nested groups)
fab api -A azure "https://graph.microsoft.com/v1.0/groups/{groupId}/transitiveMembers"

This returns all users regardless of nesting depth.

Excluding Non-Consumer Users from Metrics

When evaluating whether a report is "being used," exclude users who are not the intended consumer audience. These users inflate viewer counts and distort adoption metrics.

Users to Exclude

Practical Identification

Programmatic distinction between developers and consumers is imperfect. Use these heuristics:

1. Workspace role as a proxy: Users with Viewer role are almost always consumers. Users with Admin, Member, or Contributor roles may be developers -- cross-reference with their activity types. 2. Activity type cross-reference: Query the activity events API for the same user. If their activities include UpdateReportContent, CreateReport, or DeleteReport for this report, they are likely developers. If their only activity is ViewReport, they are consumers. 3. Ask the user: When the distinction matters, ask who the intended audience is. A report owner knows whether workspace admins are consumers or just maintainers. 4. View pattern analysis: Developers tend to have many views clustered around edit dates. Consumers tend to have views spread across regular intervals (daily, weekly).

When reporting audience reach, present two figures if developer/consumer distinction is ambiguous:

Audience reach (all users):     75% (6/8)
Audience reach (viewers only):  60% (3/5)  [excl. 3 workspace admins]

Audience Reach Calculation

This is the most reliable metric for evaluating report success. It should be evaluated in the last 7 days, 28 days, and 60 days (if possible). To calculate how effectively a report reaches its intended audience:

Reach % = (unique consumer viewers / total consumer users with access) * 100

Where:

• Unique consumer viewers = distinct UserId values from reportviews endpoint, excluding service principals and identified developers/admins
• Total consumer users with access = sum of unique human consumer principals across all access paths (deduplicated), with security groups expanded where possible

Interpreting Reach

Caveats:

• Reach only captures views within the last 30 days (WABI metrics retention)
• Embedded views and API-driven consumption may not appear in view counts
• Security group membership is not expanded unless Graph API is available; actual human audience may be larger than what the Power BI APIs show
• Guest users (B2B) may have access but not appear in standard ACL queries
• Row-level security (RLS) may further restrict what users see even if they have report access

Script Reference

Use scripts/get_report_distribution.py to check all access paths:

# Full distribution audit
python3 scripts/get_report_distribution.py -w <workspace-id> -r <report-id>

# JSON output for programmatic use
python3 scripts/get_report_distribution.py -w <workspace-id> -r <report-id> --output json

The script checks all six access paths and produces a deduplicated summary showing each user's access paths and roles.

Export to Excel Analysis

Export to Excel is one of the most impactful user behaviors in Power BI. When users routinely export data to Excel, it often signals that the report is not meeting their analytical needs... they need to manipulate, combine, or further analyze the data outside of Power BI. It can also be a risk for governance and security.

Why It Matters

Export to Excel is a key review signal because it indicates:

1. The report is a data extraction tool, not an analytical tool. Users treat the report as a pipeline to get data into Excel rather than using it for insights. 2. The semantic model may lack needed measures or calculations. Users export raw data because the report doesn't provide the aggregations or comparisons they need. 3. The report design may be insufficient. Users may need to pivot, filter, or format data in ways the report doesn't support. 4. Data governance risk. Exported data leaves the governed Power BI environment. Sensitivity labels, RLS, and audit controls no longer apply. 5. Performance impact. Large exports consume capacity resources and can slow the service for other users.

Detecting Export to Excel

Activity Events API (Fabric Admin)

Export activities are captured in the activity events log. Query with:

fab api -A powerbi "admin/activityevents?startDateTime='YYYY-MM-DDT00:00:00'&endDateTime='YYYY-MM-DDT23:59:59'"

Export-Related Activity Types

From the Fabric operation list:

For visual-level Excel exports (right-click a table/matrix -> "Export data"), the activity is ExportReport. This single event covers multiple export types:

• Data with current layout
• Summarized data (Excel)
• Summarized data (Excel live connected)
• Summarized data (CSV) -- note: CSV export may not be tracked in all cases; this has been reported as a bug
• Underlying data

The ExportEventPropertyList property in the event payload contains format details to distinguish between these export types. Inspect the raw JSON to determine the specific format.

Note: "Analyze in Excel" (AnalyzeInExcel, AnalyzedByExternalApplication) is a different consumption method, not an export. It creates a live connection to the model, not a data snapshot. Do not conflate it with visual data exports.

Timing: Activity events can take 30-60 minutes to appear in the log. Do not expect immediate results after an export.

Key Fields in Export Events

Note: the activity log schema varies per event type. Not all fields are present on every event. Retrieve raw JSON and inspect the available fields for your specific scenario.

Analyzing Export Patterns

When reviewing export activity for a report, evaluate:

1. Frequency: How often are users exporting? Daily exports suggest a workflow dependency on Excel. 2. Users: Are many users exporting, or just one? A single heavy exporter may have a specific need; widespread export suggests a report design gap. 3. Which visuals: If export events include visual/page context, identify which visuals are being exported. These visuals likely need better in-report alternatives. 4. Timing: Do exports correlate with refresh schedules? Users may be exporting fresh data for downstream processes.

Recommendations by Pattern

Other Export Activities

Download as PBIX

The DownloadReport activity indicates a user downloaded the entire report as a .pbix file. This is a significant governance concern:

• The entire semantic model data may be included (Import mode)
• The user can open it locally without RLS enforcement
• Check tenant settings: "Download reports" can be disabled

Export to PDF / PPTX

The ExportReport activity with PDF or PPTX format is generally benign -- users are taking snapshots for presentations or documentation. High frequency may indicate the report should have an email subscription instead.

Export to PNG / Image

Visual-level image export is less common but can indicate users are embedding report visuals in other documents (Confluence, SharePoint pages, presentations). Consider using Power BI embedded or the publish-to-web feature (for non-sensitive content) instead.

Querying Export Activity

To find export events for a specific report over the last 7 days:

# Iterate over the last 7 days (activity API supports 1 day per request)
for i in $(seq 0 6); do
  DATE=$(date -u -v-${i}d '+%Y-%m-%d')
  fab api -A powerbi "admin/activityevents?startDateTime='${DATE}T00:00:00'&endDateTime='${DATE}T23:59:59'" \
    -q "text.activityEventEntities[?Activity=='ExportReport' && ReportId=='<report-id>']"
done

For DownloadReport events:

fab api -A powerbi "admin/activityevents?startDateTime='${DATE}T00:00:00'&endDateTime='${DATE}T23:59:59'" \
  -q "text.activityEventEntities[?Activity=='DownloadReport' && ReportId=='<report-id>']"

Performance Audit

Complements performance.md (which covers load-time telemetry and DAX query inference). This reference covers the query cost model, the Performance Analyzer export artifact, DirectQuery report-layer tuning, and the interaction/navigation audit.

Query Cost Model

Visual count is a proxy; query cost per visual is the real driver. Opening a page refreshes every visual. Each emits at least one DAX query; several emit more. Parallelism is capped (DirectQuery Maximum Connections per Data Source defaults to 10; service capacity imposes additional limits), so total page-load latency grows non-linearly once the parallel cap is hit.

Practical implication: 12 cheap card visuals can be fine; 8 matrices with totals and measure filters may not be.

Visuals that emit more than one query (multipliers):

• Tables/matrices with totals/subtotals (one query per band; DistinctCount/Median are worst)
• Measure filters (two queries)
• Top N filters (two queries; can blow the 1M-row intermediate limit under DirectQuery)
• Field parameters (an extra evaluated-parameters phase)
• Custom/Deneb/Python/R visuals (display phase dominates)

Review without Desktop:

pbir visuals query   # read queryState per visual; flag measure-filters, TopN, totals, field params

Hidden and off-canvas visuals still query on load; include them in counts. Do not clear a flag based on visual count alone; a low-count page can be slow from one expensive visual.

Performance Analyzer Export

Performance Analyzer (Desktop-only export) produces a JSON log of every recorded operation. It is the one perf artifact parseable from the terminal without a live model. It breaks each visual's wall time into named phases:

DAX query:            model/measure work (or DirectQuery source query); fix belongs with the modeler
Direct query:         only present for DirectQuery tables; confirms live source round-trip
Visual display:       render time; high here + low DAX = report-layer cost (fixable)
Other:                queuing/serialization; large value here is a serialization symptom
Evaluated parameters: field-parameter overhead

Workflow: generate timings in Desktop, export the JSON, map each objectId/objectName to a visual.json name, apply fixes in PBIR, re-validate. Use the documented export format from microsoft/powerbi-desktop-samples rather than reverse-engineering fields.

When Desktop is unavailable, fall back to WABI reportloads telemetry (see performance.md) for absolute load times; use the Performance Analyzer export for relative attribution.

Notes:

• Durations are queue-inclusive; a high number does not prove a visual is intrinsically slow. Isolate with single-visual refresh before drawing conclusions
• The capturing machine differs from the service; use the export to find the relatively-worst visual, not to promise a specific millisecond figure

DirectQuery Report-Layer Tuning

Report-layer-only levers, all fixable inside .Report with pbir-cli. Separates "report agent can fix" from "kick to the modeler". Matters more under DirectQuery because every interaction is a live source round-trip (4-minute service timeout; 5s/30s usable/unusable guideline in practice).

Detect DirectQuery from the report side via the Performance Analyzer "Direct query" phase, or confirm storage mode via model skills before applying.

Apply before binding fields: write the filterConfig block before field bindings, or order pbir filters calls before pbir visuals bind. An unfiltered intermediate can hit the 1M-row limit.

Turn off unused totals/subtotals:

pbir visuals format <path> --property totals.show false

These generate extra source queries; always extra cost for DistinctCount/Median.

Avoid measure filters and Top N on high-cardinality columns: they generate two source queries and can exceed the 1M-row limit. If Top N is required, scope it tight and prefer a model-side aggregation.

Prefer single-select slicers, or gate multi-select behind an Apply button: the highest-leverage fix; multi-select fires a query per item added.

Disable cross-highlight from slicers to expensive visuals:

# set a NoFilter pair from slicer to matrix visual

Use visualInteractions[] with type NoFilter for slicer-to-expensive-visual pairs.

Keep visuals-per-page low: past the parallel-connection cap, visuals serialize and can show time-inconsistent results; this is a correctness argument, not just a speed one.

What not to change from `.Report`: Maximum Connections per Data Source is a model setting; recommend raising it but do not attempt to set it from .Report. Auto page refresh multiplies everything by frequency and concurrent users; flag it if present.

Do not blanket-apply DirectQuery tuning to Import reports; disabling cross-highlight removes interactivity for no gain.

Interaction and Navigation Audit

Defects that are invisible in a screenshot and do not fail pbir validate.

Cross-filter graph

Read each page's visualInteractions:

• Flag zero overrides on a page with both slicers and KPI cards; the cards likely jump on chart clicks (usually unintended)
• Flag a wall of NoFilter everywhere; interactivity may have been disabled rather than configured
• Flag overrides referencing visual names that no longer exist (stale, no-op; find by resolving names against actual visuals on the page)

Note: a NoFilter pair is sometimes correct (intentional KPI stability). Flag patterns and stale references, then ask the author about intent.

Drill propagation

Grep drillFilterOtherVisuals:

• Flag drillable visuals where page-wide drill response was clearly intended but left false
• Flag the inverse (drill response active on a page where it would confuse users)

Note: drillFilterOtherVisuals (hierarchy drill on same page) is distinct from drillthrough (page navigation).

Navigation integrity

Collect every visualLink with navigationSection/drillthroughSection/bookmark, resolve each target against actual page/bookmark names (not displayName):

• Flag dangling references
• Flag WebUrl pointing at non-HTTPS or empty URLs
• Flag navigator vs button sprawl: a row of near-identical PageNavigation buttons that a single pageNavigator would replace

Drillthrough hygiene

• Confirm drillthrough pages are hidden in the view mode or carry a clear-filters reset
• Confirm a Back button exists on drillthrough pages
• A missing local target page is expected for cross-report drillthrough; do not flag it

Resolve all targets against name, not displayName. Stale references resolve empty at runtime without a validation error.

Report Performance Analysis

Reference for evaluating Power BI report performance through load time metrics, visual complexity analysis, and query inference from report metadata.

Load Time Metrics

Percentiles Explained

P50 is the typical user experience. P90 reveals the worst-case experience for the slowest 10% of users -- often caused by slow networks, mobile devices, complex filter states, or cold cache.

A large P50-to-P90 gap indicates inconsistent performance. Investigate:

• Geographic distribution (users far from the data region)
• Browser/device variation (mobile vs desktop)
• Filter-dependent query complexity (some slicer combinations produce expensive queries)
• Cache miss patterns (first view after refresh vs subsequent views)

Retrieving Load Times

Load time data comes from the WABI reportloads endpoint (Tier 1, workspace Viewer role):

python3 scripts/get_report_usage.py -w <workspace-id>
python3 scripts/get_report_detail.py -w <workspace-id> -r <report-id>

The reportloads endpoint returns StartTime and EndTime per load event. Load time in seconds = EndTime - StartTime. Fields include LocationCity, LocationCountry, DeviceBrowserVersion, and Client for diagnosing environment-specific slowness.

For the pre-computed percentile DAX measures (P-10, P-50, P-90, P-25, 7-day variants), generate the Usage Metrics Model (Tier 2, workspace Contributor+). See references/usage-metrics.md.

Performance Audit Script

Use scripts/performance_audit.py to audit a single report's performance:

# Performance audit for a report
python3 scripts/performance_audit.py -w <workspace-id> -r <report-id>

# JSON output
python3 scripts/performance_audit.py -w <workspace-id> -r <report-id> --output json

The script collects load time metrics and analyzes the report definition for visual complexity indicators.

Visual Complexity Analysis

Performance problems in Power BI reports are almost always caused by what the visuals ask the semantic model to compute. Analyze the report definition to identify complexity hotspots.

Complexity Indicators

Reading Visual Field Bindings

Each visual's query is defined in visual.json under visual.query.queryState. The structure maps directly to the DAX query Power BI generates:

Field binding structure:

visual.query.queryState
  .<RoleName>                    -- Category, Y, Values, Rows, Columns, Series, etc.
    .projections[]
      .field
        .Column|Measure          -- Dimension or measure reference
          .Expression.SourceRef
            .Entity              -- Table name
            .Schema              -- "extension" if report-level measure
          .Property              -- Column/measure name
      .queryRef                  -- "Table.Field" fully qualified reference

Role names vary by visual type:

Inferring DAX Queries from Visual Metadata

Power BI translates each visual's field bindings into a SUMMARIZECOLUMNS query. Understanding this mapping reveals which visuals generate expensive queries.

Base pattern:

EVALUATE
SUMMARIZECOLUMNS(
    'Table1'[GroupingColumn1],              -- From Category/Rows role
    'Table2'[GroupingColumn2],              -- From Series/Columns role
    "Measure1_Alias", 'Table'[Measure1],   -- From Y/Values role
    "Measure2_Alias", 'Table'[Measure2]
)

To construct the query for a visual: 1. Collect all Column-type projections from grouping roles -- these become the first arguments to SUMMARIZECOLUMNS 2. Collect all Measure-type projections from measure roles -- these become "alias", Table[Measure] pairs 3. Check reportExtensions.json for extension measure definitions -- these may need a DEFINE block 4. Check objects for conditional formatting using measures -- these add hidden query columns

Example: A bar chart with Category: Date[Month], Y: Sales[Revenue], Sales[Margin %] generates:

EVALUATE
SUMMARIZECOLUMNS(
    'Date'[Month],
    "Revenue", 'Sales'[Revenue],
    "Margin", 'Sales'[Margin %]
)

Hidden Query Overhead

Not all DAX computation is visible in the visual's field wells. Additional query columns are generated by:

1. Conditional formatting -- All forms of conditional formatting add overhead. Measure-driven formatting (where objects.dataPoint.fill references a measure via expr.Measure) is the most expensive because it adds extra query columns evaluated per data point. Rule-based formatting and gradient fills are lighter but still increase rendering cost, especially on visuals with many data points.

2. Tooltip fields -- Custom tooltips may bind additional measures not shown in the main visual.

3. Sort-by-column -- If a column has a sortByColumn property in the model, the sort column is automatically added to the query even though it isn't displayed.

4. Data labels -- Dynamic data label formats or values may add measure evaluations.

Using DAX Queries for Performance Diagnosis

To identify which visual causes performance bottlenecks:

1. Extract field bindings from each visual's visual.json 2. Construct the equivalent SUMMARIZECOLUMNS query using the pattern above 3. Execute each query against the semantic model using the executeQueries API or DAX Studio 4. Measure execution time per query 5. Rank visuals by query cost

# Execute a DAX query against the model
fab api -A powerbi "groups/{wsId}/datasets/{datasetId}/executeQueries" \
  -X post -i '{"queries":[{"query":"EVALUATE SUMMARIZECOLUMNS(...)"}]}'

The most expensive queries reveal the visuals that need optimization. Common fixes:

• Reduce grouping columns or filter the data (page or report filters) (fewer dimensions = smaller result set)
• Simplify or remove conditional formatting where not essential
• Avoid or remove custom visuals that are overly-complex
• Audit the DAX and semantic model for issues there (see the semantic-models plugin and the semantic-model skill)

Report Metadata

Reference for retrieving and interpreting report-level metadata: thick vs thin, endorsement, sensitivity labels, deployment pipelines, and model properties.

Thick vs Thin Reports

A thin report connects to a published semantic model in the Power BI service. A thick report embeds its own semantic model (the .pbix model and report are bundled together).

Thin reports are preferred because:

• Multiple reports can share one model (single source of truth)
• Model changes propagate to all connected reports
• Separation of concerns (model team vs report team)
• Lower storage footprint

Detection

There is no direct API field for thick/thin. Infer it with these heuristics:

1. Same-name model in same workspace: If a workspace has Sales.Report and Sales.SemanticModel, the report is likely thick (auto-generated model from .pbix upload). 2. datasetWorkspaceId matches report workspace: Check the report's datasetWorkspaceId field. If it matches the report's workspace, it may be thick. If it points to a different workspace, it is thin. 3. Report-to-model ratio: A healthy workspace has more reports than models (many reports sharing few models). A 1:1 ratio suggests thick reports.

# Get report's connected model and workspace
fab api -A powerbi "groups/{wsId}/reports/{reportId}" \
  -q "{datasetId: datasetId, datasetWorkspaceId: datasetWorkspaceId, name: name}"

# List all items to compare report:model ratio
fab ls "{workspace}.Workspace" -l

DataHub V2 Fields for Models (undocumented)

The DataHub V2 API (/metadata/datahub/V2/artifacts with supportedTypes: ["Model"]) returns rich model metadata not available via standard APIs. The API is undocumented internal Microsoft surface area and may break without notice. The fields below are accessible via scripts/search_across_workspaces.py in the fabric-cli plugin (which surfaces them ahead of the identity fields shared with fab find).

Endorsement Status

Reports and models can be endorsed as Certified (verified by a designated authority) or Promoted (recommended by the owner).

Checking Endorsement

# Via workspace scanner API (Fabric Admin)
# Step 1: Trigger scan
fab api "admin/workspaces/getInfo" -X post \
  -i '{"workspaces":["<wsId>"]}'

# Step 2: Get scan result (after scan completes)
fab api "admin/workspaces/scanResult/<scanId>"
# Response includes endorsementDetails for each item

Alternatively, the admin/reports endpoint may return endorsementDetails if the report has been endorsed:

fab api -A powerbi "admin/reports/{reportId}"
# Check for endorsementDetails field (null if not endorsed)

Endorsement values:

• null -- Not endorsed
• {"endorsement": "Promoted"} -- Owner-promoted
• {"endorsement": "Certified", "certifiedBy": "user@org.com"} -- Certified by authority

Review Guidance

• Certified reports should have higher quality standards
• Promoted reports indicate the owner considers them ready for broader use
• Unendorsed reports in production workspaces may need review

Sensitivity Labels

Sensitivity labels (from Microsoft Purview) classify data confidentiality.

# Check via admin API (Fabric Admin)
fab api -A powerbi "admin/reports/{reportId}"
# Look for sensitivityLabel field

# Or via fab CLI
fab label get "{workspace}.Workspace/{report}.Report"

Review Guidance

• Reports without labels in a tenant that requires them should be flagged
• Reports with high-sensitivity labels should not have publish-to-web enabled
• Check that sensitivity labels match the data classification of the underlying model

Deployment Pipeline Membership

Check whether a report is part of a CI/CD deployment pipeline:

# List all pipelines (Fabric Admin)
fab api -A powerbi "admin/pipelines"

# Get pipeline stages
fab api -A powerbi "admin/pipelines/{pipelineId}/stages"

# Match workspace IDs to find which pipeline contains the report's workspace

Review Guidance

• Reports in deployment pipelines follow a governed promotion process (dev -> test -> prod)
• Reports NOT in a pipeline that are in production workspaces may lack change management
• Check which stage the workspace is in (dev/test/prod) to understand the report's lifecycle position

Report Format

fab api -A powerbi "groups/{wsId}/reports/{reportId}" -q "format"

Quick Metadata Checklist

When reviewing a report, collect these metadata points:

Report:     <name>
Format:     PBIR / PBIX
Type:       Thin / Thick
Model:      <model name> (Import / DirectQuery / Direct Lake)
Model size: <n> MB
Endorsed:   Certified / Promoted / None
Sensitivity: <label> / None
Pipeline:   <pipeline name> stage <n> / None
Capacity:   <SKU>
Owner:      <email>

Usage Interpretation

Guidance for reading modern Usage Metrics data accurately and converting view counts into a retire/keep/redesign decision. Avoids the failure mode of drawing wrong conclusions from structural telemetry limitations.

Modern Usage Metrics: What the Numbers Actually Mean

The modern Usage Metrics report has different metric definitions from the legacy report; treating them as equivalent produces wrong adoption verdicts.

Report View vs Report Page View

• Report View (server-side): one event per report open, reliable, matches audit logs
• Report Page View (client-side): one event per page render

Opening a report increments page views only for the landing page. "Page X has fewer page views than the report has views" is normal, not evidence the page is unused.

Structural Undercounting

Page-view undercounting is structural: ad blockers, firewalls, offline sessions, and embedded scenarios drop client telemetry silently. Low page-view counts are a floor, not a ceiling. Conclude "unused page" only when the whole report is unused, not from a page-level view count alone.

Before flagging an unused page, check:

• pbir pages list + navigators to confirm the page is reachable
• Whether the page is a tooltip page or drillthrough target (these legitimately have no direct views)

The Blank Page Entry

Blank in the page slicer is not a real page; it represents pages added in the last 24h or since deleted. Do not investigate it.

Window and Retention

• 30-day window, 30-day retention, daily refresh with up to 24h lag
• "No views" means no views in 30 days; that is the wrong window for quarterly or annual reports
• Archive via Analyze in Excel or a scheduled extract for longer trends

Blind Spots

• App report pages and paginated reports are not in the Report pages table; absence of page views does not mean no engagement
• The platform slicer understates mobile/embedded usage precisely where client telemetry drops hardest; do not cite it as proof nobody uses mobile

Confidence Calibration

Tag conclusions by confidence:

• Report-level verdicts (views, viewers, rank): high confidence
• Page-level verdicts: lower confidence; always add an explicit telemetry-loss caveat
• "No views in 30 days": medium confidence; check window vs cadence before acting

Other notes:

• Unnamed Users is a tenant privacy setting, not missing data
• A modern-vs-legacy "drop" in metrics is a definition change, not a regression

Retire / Keep / Redesign Verdict

Low usage is a question, not an answer. Use the following steps to turn view counts into a defensible action.

1. Match the window to the cadence

Read date-slicer grain, "as of" titles, and period filters to infer the report's cadence before applying a 30-day lens. An annual auditor model untouched for 11 months must be kept; a weekly operational report with no views in 30 days is a real signal.

2. Separate reach from adoption

Potential reach (people with access) vs actual reach (people who viewed it) are different numbers. A 500-person group with 8 viewers is an adoption problem, not necessarily a report problem. Investigate distribution and onboarding before touching the report.

3. Filter the viewer list

Strip before counting:

• Service principals (principalType: App)
• Report creators/owners (identified via UpdateReportContent/CreateReport activity events)
• IT/support/admin users whose only activity is maintenance access
• One-or-two-time viewers in a narrow window near the report's creation date (likely developers or testers)

After filtering, work with the remaining consumer-only count.

4. Honor exception classes

Do not retire:

• Exec scorecards viewed by a small number of high-value users
• Compliance or audit content used intermittently but critical when needed
• Reports serving a seasonal cadence outside the 30-day window

5. Read trend, not level

A downward trend on a previously-used report is a stronger retire signal than flat-low with no prior history.

6. Emit a verdict

One of four outcomes:

• Keep: active reach, trend stable or rising, exception class, or cadence outside window
• Investigate-distribution: low actual reach relative to potential reach; distribution or onboarding issue
• Redesign: used but poorly (low per-viewer frequency, declining trend, design issues explaining the drop)
• Retire: low actual reach + downward trend + no exception class + confirmed by owner/SME

Always require owner/SME confirmation as the final gate before retiring.

7. Soft-retire for code-managed reports

Rename with a deprecation prefix rather than delete; leave the definition in source control. The admin REST Get Unused Artifacts as Admin only looks back 30 days, so trend decisions need archived activity history.

Notes:

• Never recommend deletion off a single 30-day "no views"
• Permission breadth is not consumption; a widely-shared report can still be unused
• A low-but-loyal personal/team-BI report with a small dedicated audience is a valid scenario, not a failure

Power BI Report Usage APIs

Complete reference for retrieving report usage data programmatically. Includes both official (documented) and internal (undocumented) APIs.

API Tiers Overview

Tier 1 is generally the recommended default -- it provides page views and load times directly via WABI endpoints (reportpagesectionviews, reportloads) without needing to generate a model. Tier 2 is only needed for the pre-built DAX measures (trend calculations, percentile measures, rank strings). Note that 1-3 are all going via undocumented APIs.

Permission Requirements by API

Key distinction:

• Workspace roles (Viewer, Contributor, Member, Admin) are per-workspace and control access to items within that workspace
• Fabric Admin (also called Power BI Admin or Tenant Admin) is a tenant-wide role granting access to all admin/* API endpoints across all workspaces

Tier 1: WABI Metrics Endpoints (Undocumented)

Internal Power BI endpoints that return usage data without generating a model. These are the same endpoints used by the Power Query M expressions inside the Usage Metrics Report's semantic model.

Base URL: https://{cluster-host}/metadata/v201906/metrics/workspace/{workspaceId}/

The cluster host is region-specific. Common values:

Discover the cluster host from any Power BI API response's home-cluster-uri header.

reportviews

Individual report view events for the workspace (last 30 days).

GET /metadata/v201906/metrics/workspace/{wsId}/reportviews

Response fields:

reportmetadata

Report names and IDs for the workspace.

GET /metadata/v201906/metrics/workspace/{wsId}/reportmetadata

Response fields: ReportId, ReportName, WorkspaceId, OrganizationId, IsUsageMetricsReport

reportpagesectionmetadata

Page names and section IDs per report (current pages only).

GET /metadata/v201906/metrics/workspace/{wsId}/reportpagesectionmetadata

Response fields: ReportId, SectionId, SectionName, WorkspaceId

reportrank

Report view counts and organization-wide ranking.

GET /metadata/v201906/metrics/workspace/{wsId}/reportrank

Response fields:

reportpagesectionviews

Individual page-level view events with section IDs and timestamps. Joins to reportpagesectionmetadata for page names.

GET /metadata/v201906/metrics/workspace/{wsId}/reportpagesectionviews

Response fields:

reportloads

Report load time events with start/end timestamps and geographic location.

GET /metadata/v201906/metrics/workspace/{wsId}/reportloads

Response fields:

Note: Load time in seconds = (EndTime - StartTime).total_seconds(). This is the raw measurement; the Usage Metrics Model computes loadTime as a calculated column from these fields.

dashboardviews

Individual dashboard view events (same structure as reportviews).

GET /metadata/v201906/metrics/workspace/{wsId}/dashboardviews

Tier 2: Usage Metrics Model (Undocumented Generation, Official Querying)

The Usage Metrics Model is a hidden semantic model generated per workspace. It contains detailed page-level views, load times, and performance data collected from client telemetry.

Generating the Model

GET https://{cluster-host}/beta/myorg/groups/{wsId}/usageMetricsReportV2

Returns 200 or 202. The response includes the model metadata with models[0].dbName containing the dataset GUID. This is the same action as clicking "View usage metrics" in the Power BI service UI.

Requirements: Workspace Contributor, Member, or Admin role.

Querying the Model

Use the standard Power BI executeQueries API:

POST https://api.powerbi.com/v1.0/myorg/groups/{wsId}/datasets/{datasetId}/executeQueries

{
  "queries": [{"query": "EVALUATE 'Report page views'"}],
  "serializerSettings": {"includeNulls": true}
}

Available Tables

Report views -- Individual report open events (server-side telemetry).

Columns: ReportId, ReportType, ReportName, AppName, UserKey, UserId, UserAgent, DatasetName, CapacityId, CapacityName, Date, CreationTime, DistributionMethod, OriginalConsumptionMethod, ConsumptionMethod

Report page views -- Page-level view events (client-side telemetry).

Columns: AppName, UserId, ReportId, Date, Timestamp, AppGuid, Client, DeviceBrowserVersion, DeviceOSVersion, WorkspaceId, OriginalWorkspaceId, OriginalReportId, SectionId, TenantId, SessionSource, UserKey

Note: SectionId joins to Report pages.SectionId for page names.

Report pages -- Current page names per report.

Columns: ReportId, SectionId, SectionName, WorkspaceId

Report load times -- Performance data per report load (client-side telemetry).

Columns: Timestamp, PbiCluster, AppName, TenantId, UserId, ReportId, GroupId, Client, StartTime, EndTime, DeviceOSVersion, LocationCity, Country, loadTime, Date, OriginalReportId, OriginalGroupId, DeviceBrowserVersion, Browser, AppGuid, SessionSource

Reports -- Report catalog for the workspace.

Columns: OrganizationId, ReportGuid, ReportName, WorkspaceId, IsUsageMetricsReport

Users -- User lookup (derived from Report views).

Columns: UserId, UserKey, UserGuid, UniqueUser

Report rank -- Organization-wide report ranking.

Columns: ReportId, WorkspaceId, ReportViewCount, ReportRank, TotalReportCount, TenantId

Workspace views -- Aggregated views per report/user/method.

Columns: ReportId, UserId, DistributionMethod, ConsumptionMethod, Views, UserKey, UniqueUser

Model measures -- Pre-built DAX measures.

Limitations

• Page views use client telemetry; can be undercounted due to ad blockers or network issues
• Load times use client telemetry; similar undercounting risk
• Model data covers last 30 days
• Private link environments may not capture client telemetry

Tier 3: DataHub V2 API (Undocumented)

Cross-workspace metadata including lastVisitedTimeUTC -- when any user last accessed an item. The existing search_across_workspaces.py script in the fabric-cli skill provides full access to this API.

POST https://{cluster-host}/metadata/datahub/V2/artifacts

{
  "filters": [{"datahubFilterType": "workspace", "values": ["<wsId>"]}],
  "supportedTypes": ["PowerBIReport"],
  "tridentSupportedTypes": ["powerbireport"],
  "pageSize": 200,
  "pageNumber": 1
}

Unique fields not available elsewhere:

Tier 4: Activity Events API (Official, Admin Required)

The official admin API for audit logging. Returns server-side activity events for the entire tenant.

GET https://api.powerbi.com/v1.0/myorg/admin/activityevents?startDateTime='YYYY-MM-DDT00:00:00'&endDateTime='YYYY-MM-DDT23:59:59'

Key activity types for reports: ViewReport, ShareReport, UpdateReportContent, CreateReport, DeleteReport, ExportReport

Limitations:

• Only report-level events (no page views)
• Admin role required
• Maximum 1 day per request
• Up to 28 days of history
• Continuation token pagination required for large result sets
• Rate limited to 200 requests per hour

ViewReport event fields: ReportId, ReportName, ReportType, DatasetId, DatasetName, WorkspaceId, WorkSpaceName, UserId, CreationTime, DistributionMethod, ConsumptionMethod, CapacityId, CapacityName, UserAgent, ClientIP

Email Subscriptions

Email subscriptions deliver report snapshots to users on a schedule. Subscription recipients receive the report without actively viewing it in the Power BI service. This means subscription-delivered views do not count as report views in the usage metrics data. A report may have active subscribers who never appear in the view counts.

When evaluating adoption, check subscriptions separately to get a complete picture of report consumption.

Get Report Subscriptions (Admin)

fab api -A powerbi "admin/reports/{reportId}/subscriptions"

Response fields:

Get User Subscriptions (Admin)

fab api -A powerbi "admin/users/{userId}/subscriptions"

Returns all subscriptions for a specific user across all workspaces.

Subscription Activity Events

Subscription-related activities in the activity log:

Interpreting Subscriptions in a Review

• A report with 0 views but active subscriptions is being consumed passively -- it is not unused
• Count subscription recipients as part of the effective audience, but note they are passive consumers
• If subscription recipients never also view the report interactively, the report may benefit from being converted to a paginated report or automated email (lower overhead)

Analyzing View Trends

Rolling 7-Day Average

Raw daily view counts are noisy (weekends, holidays, one-off spikes). Use a rolling 7-day average to identify the underlying trend. When presenting usage data:

1. Calculate the 7-day rolling average of daily views 2. Compare the current 7-day average to the previous period 3. Flag reports where the 7-day average is declining consistently

Interpretation:

Implementation: The reportviews endpoint (Tier 1) returns individual view events with CreationTime. Group by day, compute the rolling average over 7-day windows, and compare the most recent window to the prior window.

Adjusting for Subscription Recipients

When reporting total consumption, combine:

Total active consumers = unique interactive viewers + unique subscription recipients

But note that interactive viewers and subscription recipients may overlap. Deduplicate by email address when possible.

Filtering Viewers for Accurate Adoption Metrics

Raw usage data includes views from developers, admins, and service principals alongside real consumers. For an accurate picture of report adoption, filter the viewer data.

Exclude from Consumer Metrics

Identification via Activity Events

Cross-reference viewer UserId values against the Activity Events API (Tier 4). A user whose activities for a report include UpdateReportContent, CreateReport, or DeleteReport is likely a developer, not a consumer. A user whose only activity is ViewReport is likely a consumer.

# Get activity events and filter for a specific user + report
fab api -A powerbi "admin/activityevents?startDateTime='...'&endDateTime='...'"
# Filter results by UserId and ReportId, check Activity field

View Pattern Heuristics

When activity event access is unavailable, use view patterns as a proxy:

• Developer pattern: Burst of views clustered around report edit dates, then drops off
• Consumer pattern: Regular views spread across days/weeks (daily check-in, weekly review)
• One-time tester: Views only in a narrow window near the report's creation date

Security Groups and Distribution Lists

Power BI APIs do not expand group membership. A group like Sales-Team@contoso.com appears as one ACL entry but may represent dozens of users. See references/distribution.md for how to expand groups via the Microsoft Graph API (/groups/{id}/transitiveMembers).

When group expansion is not possible, note the group names and flag that the actual audience size is unknown. The reach percentage will be inaccurate if significant access is granted via groups.

Authentication

All APIs use Azure AD bearer tokens with the Power BI API resource scope:

Resource: https://analysis.windows.net/powerbi/api

Obtain via Azure CLI:

az account get-access-token --resource https://analysis.windows.net/powerbi/api

Or via fab CLI (handles auth internally for standard API calls via fab api -A powerbi).

Exported Dataset Schema

The usage-metrics-dataset/ directory contains a full export of the Usage Metrics Report (both the .Report and .SemanticModel definitions). The TMDL files in Usage Metrics Report.SemanticModel/definition/tables/ document the complete schema including:

• Column definitions and data types
• Power Query M source expressions revealing WABI endpoint patterns
• Pre-built DAX measures for common analytics
• Relationships between tables

This is the model and report automatically generated by Power BI to compute the usage metrics. Inspect the semantic model fields if you need to extract this information. Note that you may need to first generate / refresh the usage metrics model.