Report Metadata Type Reference

The Report metadata type represents a custom analytics report in Salesforce (Tabular, Summary, Matrix, or MultiBlock Joined Report). Introduced in API version 14.0 (with aggregateFilters added in API v64.0 and crossFilters documented in v68.0), Report encapsulates displayed columns, row and column groupings (groupingsDown, groupingsAcross), custom summary formulas (aggregates), row-level formulas (customDetailFormulas), bucket fields (buckets), and embedded charts (chart).

In Salesforce DX projects, reports are stored inside folder subdirectories at force-app/main/default/reports/<FolderName>/<ReportDeveloperName>.report-meta.xml.

Key Metadata Fields#

Production-Grade XML Example (Summary Report with Custom Summary Formula)#

Below is a Summary report (force-app/main/default/reports/Executive_Sales_Reports/Quarterly_Enterprise_Pipeline.report-meta.xml) grouped by StageName with a win-rate custom summary formula:

<?xml version="1.0" encoding="UTF-8"?>
<Report xmlns="http://soap.sforce.com/2006/04/metadata">
    <aggregates>
        <calculatedFormula>WON:SUM / RowCount</calculatedFormula>
        <datatype>percent</datatype>
        <developerName>FORMULA1</developerName>
        <isActive>true</isActive>
        <isCrossBlock>false</isCrossBlock>
        <masterLabel>Stage Win Rate %</masterLabel>
        <scale>1</scale>
    </aggregates>
    <columns>
        <field>OPPORTUNITY_NAME</field>
    </columns>
    <columns>
        <field>ACCOUNT_NAME</field>
    </columns>
    <columns>
        <aggregateTypes>Sum</aggregateTypes>
        <aggregateTypes>Average</aggregateTypes>
        <field>AMOUNT</field>
    </columns>
    <columns>
        <field>CLOSE_DATE</field>
    </columns>
    <description>Executive pipeline summary grouped by stage for the current fiscal quarter.</description>
    <filter>
        <criteriaItems>
            <column>AMOUNT</column>
            <columnToColumn>false</columnToColumn>
            <isUnlocked>true</isUnlocked>
            <operator>greaterOrEqual</operator>
            <value>50000</value>
        </criteriaItems>
    </filter>
    <format>Summary</format>
    <groupingsDown>
        <dateGranularity>Day</dateGranularity>
        <field>STAGE_NAME</field>
        <sortOrder>Asc</sortOrder>
    </groupingsDown>
    <name>Quarterly Enterprise Pipeline</name>
    <reportType>Opportunity</reportType>
    <scope>organization</scope>
    <showDetails>true</showDetails>
    <showGrandTotal>true</showGrandTotal>
    <showSubTotals>true</showSubTotals>
    <timeFrameFilter>
        <dateColumn>CLOSE_DATE</dateColumn>
        <interval>INTERVAL_CURRENT</interval>
    </timeFrameFilter>
</Report>

<types>
    <members>Sales_Ops/</members>
    <members>Sales_Ops/EMEA_Reports/</members>
    <members>Sales_Ops/EMEA_Reports/Quarterly_Enterprise_Pipeline</members>
    <name>Report</name>
</types>

Querying Reports and Folders with SOQL#

-- 1. List all public and shared Reports with their Folder DeveloperName
SELECT Id, Name, DeveloperName, FolderName, Format, LastRunDate, LastViewedDate
FROM Report
WHERE FolderName != 'Private Reports'
ORDER BY FolderName, Name ASC

-- 2. List all Report Folders to construct package.xml paths
SELECT Id, Name, DeveloperName, AccessType, Type
FROM Folder
WHERE Type = 'Report' AND DeveloperName != null
ORDER BY DeveloperName ASC

Frequently asked questions

Why can I not use the asterisk (*) wildcard with Report in package.xml?

Report is a foldered metadata type (inFolder = true) and does not support the asterisk wildcard in package.xml. You must list the explicit FolderDeveloperName/ReportDeveloperName path for each report.

Why do I need a trailing slash when referencing a nested ReportFolder in package.xml?

Without a trailing slash, Metadata API interprets TopFolder/SubFolder as a report named SubFolder inside TopFolder and fails. Appending a trailing slash (TopFolder/SubFolder/) tells the API that the member is a nested folder.

What happens if I redeploy a Report with the same fullName as a previously deleted report?

Redeploying a Report with the same fullName as a deleted report (even one purged from the Recycle Bin) restores the original report record along with its original 18-character Id, CreatedDate, and CreatedById.

What are the valid values for the format field on a Report?

Valid format values are Tabular (flat list of rows), Summary (grouped rows with subtotals via groupingsDown), Matrix (2D grid using both groupingsDown and groupingsAcross), and MultiBlock (Joined Report across up to 5 blocks).

How can I list all Report developer names and folders using SOQL to build a package.xml?

Query SELECT Id, DeveloperName, Name, FolderName, OwnerId, Format FROM Report WHERE OwnerId IN (SELECT Id FROM Folder WHERE Type = 'Report') in standard SOQL.