Salesforce Reports and Dashboards REST API Developer Guide

Salesforce Reports and Dashboards REST API
Examples: Reports REST API Resources
Examples: Dashboards REST API Resources
Examples: Analytics Notifications REST API
Reports API Resource Reference
Report
Describe
Execute Sync
Execute Async
Instances List
Instance Results
Report List
Query
Report Error Codes
Report Types API Resource Reference
Dashboards API Resource Reference
Analytics Notifications API Resource Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Query

Returns report data without saving changes to an existing report or creating a new one.

Resource URL

1/services/data/<latest API version>/analytics/reports/query

Formats

JSON

HTTP Methods

Method Description
POST Run a report without creating or saving the report. Customize your report using reportMetadata that you specify in the request body. See this example.

Request Body

Report metadata
Property Type Description
aggregates Array of strings
Unique identities for summary or custom summary formula fields in the report. For example:
  • a!Amount represents the average for the Amount column.
  • s!Amount represents the sum of the Amount column.
  • m!Amount represents the minimum value of the Amount column.
  • x!Amount represents the maximum value of the Amount column.
  • s!<customfieldID> represents the sum of a custom field column. For custom fields and custom report types, the identity is a combination of the summary type and the field ID.
buckets Bucket field Describes a bucket field.
chart Chart[] Details about the chart used in a report.
crossFilters Cross filter[] Cross filters applied to the report.
customSummaryFormula Custom summary formula Describes a custom summary formulas.
currency String Report currency, such as USD, EUR, GBP, for an organization that has Multi-Currency enabled. Value is null if the organization does not have Multi-Currency enabled.
detailColumns Array of strings Unique API names for the fields that have detailed data.
developerName String Report API name.
division String

Determines the division of records to include in the report. For example, West Coast and East Coast.

Available only if your organization uses divisions to segment data and you have the “Affected by Divisions” permission. If you do not have the “Affected by Divisions” permission, your reports include records in all divisions.
folderId String ID of the folder that contains the report.

When the report is in the My Personal Custom Reports folder, folderId = userId. When the report is in the Unfiled Public Reports folder, folderId = orgId.

Note
groupingsAcross Groupings across[] Unique identities for each column grouping in a report. The identity is:
  • An empty array for reports in summary format as it can’t have column groupings.
  • BucketField_(ID) for bucket fields.
  • ID of a custom field when the custom field is used for a column grouping.
groupingsDown Groupings down[] Unique identities for each row grouping in a report. The identity is:
  • BucketField_(ID) for bucket fields.
  • ID of a custom field when the custom field is used for grouping.
hasDetailRows Boolean Indicates whether to include detailed data with the summary data.
hasRecordCount Boolean Indicates whether the report shows the record count.
historicalSnapshotDates Array of strings List of historical snapshot dates.
id String Unique report ID.
name String Display name of the report.
reportBooleanFilter String Logic to parse custom field filters. Value is null when filter logic is not specified.

This is an example of a report filtered to show opportunities for accounts that are either of customer or partner type OR their annual revenue exceeds 100K AND they are medium or large sized businesses. The filters are processed by the logic, “(1 OR 2) AND 3.”

1{
2...
3        "reportBooleanFilter": "(1 OR 2) AND 3",
4        "reportFilters": [
5            {
6                "value": "Analyst,Integrator,Press,Other",
7                "column": "TYPE",
8                "operator": "notEqual"
9            },
10            {
11                "value": "100,000",
12                "column": "SALES",
13                "operator": "greaterThan"
14            },
15            {
16                "value": "Small",
17                "column": "Size",
18                "operator": "notEqual"
19            }
20        ]
21    }
22}
reportFilters Filter details[] List of each custom filter in the report along with the field name, filter operator, and filter value.
reportFormat String Format of the report. Value can be:
  • TABULAR
  • SUMMARY
  • MATRIX
reportType Report type Unique API name and display name for the report type.

type: Of type string, this is the unique identifier of the report type.

label: Of type string, this is the display name of the report type.
scope String Defines the scope of the data on which you run the report. For example, you can run the report against all opportunities, opportunities you own, or opportunities your team owns. Valid values depend on the report type.
showGrandTotal Boolean Indicates whether the report shows the grand total.
showSubtotals Boolean Indicates whether the report shows subtotals, such as column or row totals.
sortBy Array of strings API name of the field on which the report is sorted and the direction of the sort (asc or desc).
standardDateFilter Array of strings Standard date filters available in reports. Each standard date filter contains the following properties:

column: API name of the date field on which you filter the report data.

durationValue: The range for which you want to run the report. The value is a date literal or 'CUSTOM.'

startDate: Start date.

endDate: End date.
standardFilters Array of strings List of filters that show up in the report by default. The filters vary by report type. For example, standard filters for reports on the Opportunity object are Show, Opportunity Status, and Probability. This list appears as name-value string pairs.
supportsRoleHierarchy Boolean Indicates whether the report type supports role hierarchy filtering (true) or not (false).
topRows Top rows Describes a row limit filter applied to the report.
userOrHierarchyFilterId String Unique user or role ID of the user or role used by the report's role hierarchy filter.

If specified, a role hierarchy filter is applied to the report. If unspecified, no role hierarchy filter is applied to the report.
Chart
Property Type Description
chartType String Type of chart.
groupings String Report grouping.
hasLegend Boolean Indicates whether the report has a legend.
showChartValues Boolean Indicates whether the report shows chart values.
summaries Array of strings Unique identities for summary or custom summary formula fields in the report. For example:
  • a!Amount represents the average for the Amount column.
  • s!Amount represents the sum of the Amount column.
  • m!Amount represents the minimum value of the Amount column.
  • x!Amount represents the maximum value of the Amount column.
  • s!<customfieldID> represents the sum of a custom field column. For custom fields and custom report types, the identity is a combination of the summary type and the field ID.
summaryAxisLocations String Specifies the axis that shows the summary values. Valid values are X and Y.
title String Name of the chart.
Groupings down
Property Type Description
name String API name of the field used as a row grouping.
sortOrder String Order in which data is sorted within a row grouping. Value can be:
  • Asc for ascending order.
  • Desc for descending order.
dateGranularity String Interval set on a date field that’s used as a row grouping. Value can be:
  • Day
  • Calendar Week
  • Calendar Month
  • Calendar Quarter
  • Calendar Year
  • Fiscal Quarter
  • Fiscal Year
  • Calendar Month in Year
  • Calendar Day in Month
sortAggregate String Summary field that’s used to sort data within a grouping in a report that’s in summary format. Applies if you have the Aggregate Sort feature enabled as part of its pilot program. The value is null when data within a grouping is not sorted by a summary field. In this example, data grouped by Account Owner is sorted by the sum of Annual Revenue.
1{
2    "aggregates": ["s!SALES","RowCount"],
3    "groupingsDown": [
4        {
5            "name": "USERS.NAME",
6            "sortOrder": "Desc",
7            "dateGranularity": "None",
8            "sortAggregate": "s!SALES"
9        }
10    ]
11}
Groupings across
Property Type Description
name String API name of the field used as a column grouping.
sortOrder String Order in which data is sorted within a column grouping. Value can be:
  • Asc for ascending order.
  • Desc for descending order.
dateGranularity String Interval set on a date field used as a column grouping. Value can be:
  • Day
  • Calendar Week
  • Calendar Month
  • Calendar Quarter
  • Calendar Year
  • Fiscal Quarter
  • Fiscal Year
  • Calendar Month in Year
  • Calendar Day in Month
Filter details
Property Type Description
column String Unique API name for the field that’s being filtered.
isRunPageEditable Boolean Indicates if this is an editable filter in the user interface.
operator String Unique API name for the condition used to filter a field such as “greater than” or “not equal to.” Filter conditions depend on the data type of the field. Valid values are:
  • equals
  • notEqual
  • lessThan
  • greaterThan
  • lessOrEqual
  • greaterOrEqual
  • contains
  • notContain
  • startsWith
  • includes
  • excludes
  • within (DISTANCE criteria only)
value String Value by which a field is filtered. For example, the field Age can be filtered by a numeric value.

For datetime fields, if you make a POST request and specify a calendar date without including a time, then a default time gets included. The time defaults to midnight minus the difference between your timezone and Greenwich Mean Time (GMT). For example, if you specify 8/8/2015 and your timezone is Pacific Standard Time (GMT-700), then the API returns 2015-08-08T07:00:00Z.
Bucket field
Property Type Description
bucketType BucketType The type of bucket. Possible values are number, percent, and picklist
developerName String API name of the bucket.
label String User-facing name of the bucket.
nullTreatedAsZero Boolean Specifies whether null values are converted to zero (true) or not (false).
otherBucketLabel String Name of the fields grouped as “Other” (in buckets of BucketType PICKLIST).
sourceColumnName String Name of the bucketed field.
values Array of BucketTypeValues Describes the values included in the bucket field..
Bucket field value
Property Type Description
label String The user-facing name of the bucket.
sourceDimensionValues String A list of the values from the source field included in this bucket category (in buckets of type PICKLIST and buckets of type TEXT).
rangeUpperBound Double The greatest range limit under which values are included in this bucket category (in buckets of type NUMBER).
Cross filter
Property Type Description
criteria Array of Filter details[] Information about how to filter the relatedEntity. Use to relate the primary entity with a subset of the relatedEntity.
includesObject Boolean Specifies whether objects returned have a relationship with the relatedEntity (true) or not (false).
primaryEntityField String The name of the object on which the cross filter is evaluated.
relatedEntity String The name of the object that the primaryEntityField is evaluated against. (The right-hand side of the cross filter).
relatedEntityJoinField String The name of the field used to join the primaryEntityField and relatedEntity.
Custom summary formula
Property Type Description
label String The user-facing name of the custom summary formula.
description String The user-facing description of the custom summary formula.
formulaType String The format of the numbers in the custom summary formula. Possible values are number, currency, and percent.
decimalPlaces Integer The number of decimal places to include in numbers.
downGroup String The name of a row grouping when the downGroupType is CUSTOM. Null otherwise.
downGroupType String Where to display the aggregate of the custom summary formula. Possible values are all, custom, and grand_total.
acrossGroup String The name of a column grouping when the accrossGroupType is CUSTOM. Null otherwise.
acrossGroupType String Where to display the aggregate of the custom summary formula. Possible values are all, custom, and grand_total.
formula String The operations performed on values in the custom summary formula.
Top rows
Property Type Description
rowLimit Integer The number of rows returned in the report.
direction String The sort order of the report rows.

Response Body

Property Type Description
attributes Attributes Key report attributes and child resource URLs.
allData Boolean

When True, all report results are returned.

When False, results are returned for the same number of rows as a report run in Salesforce.

For reports that have too many records, use filters to refine results.

Note
factMap Fact map Summary level data or both summary and detailed data for each row or column grouping. Detailed data is available if hasDetailRows is true.

Each row or column grouping is represented by combination of row and column grouping keys defined in Groupings down and Groupings across.

See these examples of fact map keys.
groupingsAcross Groupings across Collection of column groupings, keys, and their values.
groupingsDown Groupings down Collection of row groupings, keys, and their values.
hasDetailRows Boolean

When true,the fact map returns values for both summary level and record level data.

When false, the fact map returns summary values.
reportExtendedMetadata Report extended metadata Additional information about columns, summaries, and groupings.
reportMetadata Report metadata Unique identifiers for groupings and summaries.
Attributes
Property Type Description
describeUrl String Resource URL to get report metadata.
instancesUrl String Resource URL to run a report asynchronously. The report can be run with or without filters to get summary or both summary and detailed data. Results of each instance of the report run are stored under this URL.
type String API resource format.
reportName String Display name of the report.
reportId String Unique report ID.
Fact map
Property Type Description
rows Data cells[] Array of detailed report data listed in the order of the detail columns provided by the report metadata.
aggregates Aggregates[] Summary level data including record count for a report.
Data cells
Property Type Description
value Detail column info data type The value of a specified cell.
label String Display name of the value as it appears for a specified cell in the report.
Aggregates
Property Type Description
value Number Numeric value of the summary data for a specified cell.
label String Formatted summary data for a specified cell.
Groupings across
Property Type Description
groupings Groupings[] Information for each column grouping as a list.
Groupings
Property Type Description
value String Value of the field used as a row or column grouping. The value depends on the field’s data type.
  • Currency fields:
    • amount: Of type currency. Value of a data cell.
    • currency: Of type picklist. The ISO 4217 currency code, if available; for example, USD for US dollars or CNY for Chinese yuan. (If the grouping is on the converted currency, this is the currency code for the report and not for the record.)
  • Picklist fields: API name. For example, a custom picklist field, Type of Business with values 1, 2, 3 for Consulting, Services, and Add-On Business, has 1, 2, or 3 as the grouping value.
  • ID fields: API name.
  • Record type fields: API name.
  • Date and time fields: Date or time in ISO-8601 format.
  • Lookup fields: Unique API name. For example, for the Opportunity Owner lookup field, the ID of each opportunity owner’s Chatter profile page can be a grouping value.
key String Unique identity for a row or column grouping. The identity is used by the fact map to specify data values within each grouping.
label String Display name of a row or column grouping. For date and time fields, the label is the localized date or time.
groupings Array Second or third level row or column groupings. If there are none, the value is an empty array.
dategroupings Array Start date and end date of the interval defined by date granularity.
Groupings down
Property Type Description
groupings Groupings[] Information for each row grouping as a list.