Reports and Dashboards REST API

Reports and Dashboards REST API enhancements include new methods of report and dashboard folders, a URL parameter for the notifications resource to scope resources to Lightning dashboard subscriptions, new resources for report types, and new report and dashboard properties.

For more information, see the Reports and Dashboards REST API Developer Guide.

New Resources and Parameters: notifications?source=lightningDashboardSubscribe, related-objects, and ​text-values

The notifications?source parameter supports a new value, notifications?source=lightningDashboardSubscribe, that describes Lightning dashboard subscriptions. The reportTypes/<primary_object_name>/related-objects resource describes secondary objects available for a specified primary object in cross filters. The text-values resource returns and lets you search text field values.
Resource URI Supported HTTP Methods Description


Return a list of recent notifications describing Lightning dashboard subscriptions (GET).



Returns an array of secondary objects available for use with a primary object in a cross filter.


Returns an array of supported filter values for a secondary object in a cross filter. Not all objects are available as secondary objects. The primary object determines which secondary objects are supported. To get a list of supported secondary objects for a specified primary object, make a GET request to /services/data/v42.0/analytics/​reportTypes/<primary_object_name> and refer to the objectRelationships property of reportTypeMetadata.


Returns textValues, which is an array of up to 200 values returned by the specified column.

Also returns the hasMore property, which is a Boolean field that indicates whether there are more than 200 items in the textValues array (true) or not (false).

For example, make a GET request to /services/data/​v42.0/analytics/​reportTypes/Opportunity/​text-values/ACCOUNT_NAME. The response is:

 "hasMore" : false,
 "textValues" : [ "Acme", "Global Media", "Global Retail" ]

Optionally, use the searchTerm URL parameter to return only values that start with the value of searchTerm.

For example, make a GET request to /services/data/​v42.0/analytics/​reportTypes/Opportunity/​text-values/​ACCOUNT_NAME?searchTerm=Acme. The response is:

 "hasMore" : false,
 "textValues" : [ "Acme" ]

New Methods: folders

The folders/ REST API supports new methods that allow you to create, rename, and delete report and dashboard folders.
Resource URI Supported HTTP Method Description
/services/data/v42.0/folders POST Creates report or dashboard folder with the specified name, label, and type.
/services/data/v42.0/folders/​<folderid> GET Gets information about a report or dashboard folder.
/services/data/v42.0/folders/​<folderid> PATCH

Updates the label of a report or dashboard folder.

/services/data/v42.0/folders/​<folderid> DELETE Deletes a report or dashboard folder.

Changed Resources: dashboardMetadata and reportTypeMetadata

We’ve updated report and dashboard metadata to describe newly available features in Lightning Experience. Report metadata now describes bucket columns and cross filters. Dashboard metadata now describes color palette and theme.
Reports and Report Types
The reportTypeMetadata object includes new properties that describe bucketing, cross filters, and role hierarchy filters.
Property Type Description
bucketable Boolean Indicates whether a field is can be used as the basis for a bucket column (true) or not (false).
saveRoleHierarchy Boolean Indecates whether a role hierarchy filter should be saved (true) or not (false).
objectRelationships objectRelationship[] reportTypeMetadata has a new property, objectRelationships, which is an array of objects (also called entities). Each object is named for a primary object, and describes the relationship between itself and related objects. The objectRelationships array is useful for seeing which objects are available for use as secondary objects on cross filters for a specified primary object. It describes how each secondary object joins with the primary object. Here are the properties of each object in the objectRelationships array:
  • label—User-facing name of the primary object.
  • primaryEntityField—Field on which secondary objects join with the primary object.
  • relatedObjects—An array of secondary objects. Each object has these properties:
    • label—User-facing name of the secondary object.
    • relatedEntity—API name of the secondary object
    • relatedEntityJoinField—The field on which the secondary object joins with the primary object.

The reportTypes object includes a new property indicating whether an administrator has hidden the report type.

Property Type Description
isHidden Boolean Indicates whether an administrator has hidden the report type (true) or not (false). Hidden report types don’t appear in the report builder when creating a report.

The buckets array of bucket objects has a deprecated property, replaced by a new property.

Property Type Description
devloperName String Deprecated in API version 42.0. Use developerName instead.
developerName String API name of the bucket.
The dashboardMetadata object has new properties that describe dashboard color palette and theme.
Property Type Description
chartTheme String Specifies the dashboard theme. Possible values are:
  • light—Default value. Dashboards have a light background that resembles a glass of milk.
  • dark—Dashboards have a dark background that is reminiscent of the night sky.
colorPalette String Specifies a color palette for use in charts. Possible values are:
  • wildflowers—Default value.
  • aurora
  • nightfall
  • sunrise
  • bluegrass
  • ocean
  • heat
  • dusk
  • pond
  • watermelon
  • fire
  • water
  • lake
  • mineral—Accessible.