Salesforce Reports and Dashboards REST API Developer Guide

Salesforce Reports and

Dashboards REST API

Developer Guide

Version 41.0, Winter ’18

@salesforcedocs

Last updated: September 21, 2017

©

Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc., as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS

Chapter 1: Salesforce Reports and Dashboards REST API

. . . . . . . . . . . . . . . . . . . . . . . 1

Requirements and Limitations

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 2: Examples: Reports REST API Resources

. . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Create a New Report

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Run Reports Synchronously or Asynchronously

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Get Report Metadata

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Get a List of Report Types

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

List Asynchronous Runs of a Report

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Filter Reports on Demand

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

List Recently Viewed Reports

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Decode the Fact Map

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Get Report Data without Saving Changes to or Creating a Report

. . . . . . . . . . . . . . . . . . . . . 58

Save Changes to Reports

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Clone Reports

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Delete Reports

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Chapter 3: Examples: Dashboards REST API Resources

. . . . . . . . . . . . . . . . . . . . . . . 73

Get List of Recently Used Dashboards

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Get Dashboard Results

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Filter Dashboard Results

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Get Dashboard Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Refresh a Dashboard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Save a Dashboard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Set a Sticky Dashboard Filter

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Return Details About Dashboard Components

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Get Dashboard Metadata

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Clone a Dashboard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Delete a Dashboard

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 4: Examples: Analytics Notifications REST API

. . . . . . . . . . . . . . . . . . . . . . . . 110

Get Analytics Notifications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Create an Analytics Notification

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Save Changes to an Analytics Notification

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Delete an Analytics Notification

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Check Limits for Analytics Notifications

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 5: Reports API Resource Reference

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Report

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Describe

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Contents

Execute Sync

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Execute Async

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Instances List

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Instance Results

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Report List

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Query

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Report Fields

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Report Error Codes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Chapter 6: Report Types API Resource Reference

. . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Report Type List

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Report Type

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Chapter 7: Filter Operators API Resource Reference

. . . . . . . . . . . . . . . . . . . . . . . . . 204

Filter Operator List

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Chapter 8: Dashboards API Resource Reference

. . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Dashboard List

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Dashboard Results

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Dashboard Describe

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Dashboard Status

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Dashboard Filter Options Analysis

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Dashboard and Component Error Codes

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Chapter 9: Analytics Notifications API Resource Reference

. . . . . . . . . . . . . . . . . . . . 234

Analytics Notification List

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Analytics Notification

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Analytics Notification Limits

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Chapter 10: Analytics Folders API Resource Reference

. . . . . . . . . . . . . . . . . . . . . . . 247

Folder Share Information

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Folder Shares

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Folder Share by ID

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Folder Share Recipients

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

INDEX

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

CHAPTER 1

Salesforce Reports and Dashboards REST API

In this chapter ...

•

Requirements and

Limitations

The Reports and Dashboards REST API gives you programmatic access to your report and dashboard data as defined in the report builder and dashboard builder. The API lets you integrate the data into any web or mobile application, inside or outside the Salesforce platform. For example, you might use the

API to trigger a Chatter post with a snapshot of top-performing reps each quarter.

The Reports and Dashboards REST API will revolutionize the way you access and visualize your data. You can:

•

Integrate report data into custom objects.

•

Define rich visualizations on top of the API to animate the data.

•

Build custom dashboards.

•

Automate reporting tasks.

At a high level, the API resources let you query and filter report data. You can:

•

Run tabular, summary, or matrix reports synchronously or asynchronously.

•

Filter for specific data on the fly.

•

Query report metadata.

You can also work with dashboard resources to:

•

Get a list of recently used dashboards.

•

Get dashboard metadata and data.

•

Query dashboard status.

•

Refresh dashboards.

1

Salesforce Reports and Dashboards REST API Requirements and Limitations

Requirements and Limitations

The Reports and Dashboards REST API is available for any organization that has API enabled. You must establish an authenticated session using OAuth in order to access the Reports and Dashboards REST API. When working with this API, consider these restrictions in addition to general API limits.

Note: Responses and requests are in JSON. While using the Reports and Dashboards REST API with a POST request body, you must use content-type: application/json. You might get unexpected results if you don’t use this content type.

Reports Limits

•

Cross filters, standard report filters, and filtering by row limit are unavailable when filtering data.

•

Historical trend reports are only supported for matrix reports.

•

The API can process only reports that contain up to 100 fields selected as columns.

•

A list of up to 200 recently viewed reports can be returned.

•

Your org can request up to 500 synchronous report runs per hour.

•

The API supports up to 20 synchronous report run requests at a time.

•

A list of up to 2,000 instances of a report that was run asynchronously can be returned.

•

The API supports up to 200 requests at a time to get results of asynchronous report runs.

•

Your organization can request up to 1,200 asynchronous requests per hour.

•

Asynchronous report run results are available within a 24-hour rolling period.

•

The API returns up to the first 2,000 report rows. You can narrow results using filters.

•

You can add up to 20 custom field filters when you run a report.

Dashboards Limits

•

Your org can request up to 200 dashboard refreshes per hour.

•

Your org can request results for up to 5,000 dashboards per hour.

Analytics Notification Limits

•

Each user can subscribe to up to 5 reports.

•

Each user can create up to 5 Wave notifications.

Note: All limits that apply to reports created in the report builder also apply to the API, as do limits for dashboards created in the dashboard builder. For more information, see “Salesforce Reports and Dashboards Limits” in the Salesforce online help.

2

In this chapter ...

•

Create a New Report

•

Run Reports

Synchronously or

Asynchronously

•

Get Report Metadata

•

Get a List of Report

Types

•

List Asynchronous

Runs of a Report

•

Filter Reports on

Demand

•

List Recently Viewed

Reports

•

Decode the Fact Map

•

Get Report Data without Saving

Changes to or

Creating a Report

•

Save Changes to

Reports

•

Clone Reports

•

Delete Reports

CHAPTER 2

Examples: Reports REST API Resources

The Reports and Dashboards REST API is designed to let you query report data easily. Use the API to:

•

Run Reports Synchronously or Asynchronously

.

Run a report immediately or asynchronously to get summary data with or without details. We recommend that you run reports asynchronously to avoid report timeouts and other API limits.

•

Get Report Metadata

.

Get information about fields in the report and report type. This includes information about fields used for report groupings, summaries, detailed data, and filters.

•

List Asynchronous Runs of a Report

.

Get a list of all instances of a report run asynchronously.

•

Filter Reports on Demand

.

Get specific data back by running a report with filter changes in the metadata.

•

List Recently Viewed Reports

Get most recently viewed reports that you have permission to access.

•

Decode the Fact Map .

Get a visualized view of your report data.

•

Save Changes to Reports

Save changes to reports.

•

Clone Reports

Make copies of existing reports.

•

Delete Reports

Clean up unused and obsolete reports.

3

Examples: Reports REST API Resources Create a New Report

Create a New Report

Create a new report using a POST request.

Example Usage

/services/data/v39.0/analytics/reports

Example Request Body

To create a report, you only have to specify reportMetadata

with a name

and a reportType

to create a new report. Other properties are optional.

{

"reportMetadata": {

"name":"NewReport",

"reportType": {

"type" : "Opportunity"

}

}

}

Example Response Body

The response includes the new report’s reportExtendedMetadata

, reportMetadata

, and reportTypeMetadata

.

{

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"RowCount" : {

"dataType" : "int",

"label" : "Record Count"

},

}

"detailColumnInfo" : {

"ROLLUP_DESCRIPTION" : {

"dataType" : "string",

"label" : "Owner Role"

},

"FULL_NAME" : {

},

"dataType" : "string",

"label" : "Opportunity Owner"

"ACCOUNT_NAME" : {

"dataType" : "string",

},

"label" : "Account Name"

"OPPORTUNITY_NAME" : {

"dataType" : "string",

},

"label" : "Opportunity Name"

"STAGE_NAME" : {

"dataType" : "picklist",

"label" : "Stage"

},

"FISCAL_QUARTER" : {

"dataType" : "string",

"label" : "Fiscal Period"

4

Examples: Reports REST API Resources Create a New Report

},

"AMOUNT" : {

"dataType" : "currency",

"label" : "Amount"

},

"PROBABILITY" : {

"dataType" : "percent",

"label" : "Probability (%)"

},

"AGE" : {

"dataType" : "int",

},

"label" : "Age"

"CLOSE_DATE" : {

"dataType" : "date",

},

"label" : "Close Date"

"CREATED_DATE" : {

"dataType" : "datetime",

"label" : "Created Date"

},

"NEXT_STEP" : {

"dataType" : "string",

"label" : "Next Step"

},

"LEAD_SOURCE" : {

"dataType" : "picklist",

"label" : "Lead Source"

},

"TYPE" : {

"dataType" : "picklist",

"label" : "Type"

}

},

"groupingColumnInfo" : { }

},

"reportMetadata" : {

"aggregates" : [ "RowCount" ],

"chart" : null,

"crossFilters" : [ ],

"currency" : null,

"description" : null,

"detailColumns" : [ "ROLLUP_DESCRIPTION", "FULL_NAME", "ACCOUNT_NAME",

"OPPORTUNITY_NAME", "STAGE_NAME", "FISCAL_QUARTER", "AMOUNT", "PROBABILITY", "AGE",

"CLOSE_DATE", "CREATED_DATE", "NEXT_STEP", "LEAD_SOURCE", "TYPE" ],

"developerName" : "DocTest2_mG",

"division" : null,

"folderId" : "005R0000000Kg8cIAC",

"groupingsAcross" : [ ],

"groupingsDown" : [ ],

"hasDetailRows" : true,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OR0000000PYkiMAG",

5

Examples: Reports REST API Resources

"name" : "DocTest2",

"reportBooleanFilter" : null,

"reportFilters" : [ ],

"reportFormat" : "TABULAR",

"reportType" : {

"label" : "Opportunities",

},

"type" : "Opportunity"

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CLOSE_DATE",

"durationValue" : "THIS_FISCAL_QUARTER",

"endDate" : "2016-12-31",

"startDate" : "2016-10-01"

},

"standardFilters" : [ {

"name" : "open",

"value" : "all"

}, {

"name" : "probability",

"value" : ">0"

} ],

"supportsRoleHierarchy" : true,

},

"userOrHierarchyFilterId" : null

"reportTypeMetadata" : {

"categories" : [ {

"columns" : {

"CREATED" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Created By"

"CREATED_ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Created Alias"

},

"LAST_UPDATE_BY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Last Modified By"

},

"LAST_UPDATE_BY_ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Last Modified Alias"

6

Create a New Report

Examples: Reports REST API Resources

},

"OPPORTUNITY_NAME" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Name"

},

"TYPE" : {

"dataType" : "picklist",

"filterValues" : [ {

"label" : "Existing Business",

"name" : "Existing Business"

}, {

"label" : "New Business",

"name" : "New Business"

} ],

"filterable" : true,

},

"label" : "Type"

"LEAD_SOURCE" : {

"dataType" : "picklist",

"filterValues" : [ {

"label" : "Advertisement",

"name" : "Advertisement"

}, {

"label" : "Employee Referral",

"name" : "Employee Referral"

}, {

"label" : "External Referral",

"name" : "External Referral"

}, {

"label" : "Partner",

"name" : "Partner"

}, {

"label" : "Public Relations",

"name" : "Public Relations"

}, {

"label" : "Seminar - Internal",

"name" : "Seminar - Internal"

}, {

"label" : "Seminar - Partner",

"name" : "Seminar - Partner"

}, {

"label" : "Trade Show",

"name" : "Trade Show"

}, {

"label" : "Web",

"name" : "Web"

}, {

"label" : "Word of mouth",

"name" : "Word of mouth"

}, {

"label" : "Other",

"name" : "Other"

7

Create a New Report

Examples: Reports REST API Resources

} ],

"filterable" : true,

},

"label" : "Lead Source"

"PARTNER_NAME" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Primary Partner"

"AMOUNT" : {

"dataType" : "currency",

"filterValues" : [ ],

"filterable" : true,

"label" : "Amount"

},

"CLOSED" : {

"dataType" : "boolean",

"filterValues" : [ {

"label" : "True",

"name" : "True"

}, {

"label" : "False",

"name" : "False"

} ],

"filterable" : true,

},

"label" : "Closed"

"WON" : {

"dataType" : "boolean",

"filterValues" : [ {

"label" : "True",

"name" : "True"

}, {

"label" : "False",

"name" : "False"

} ],

"filterable" : true,

"label" : "Won"

},

"CLOSE_DATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Close Date"

"CLOSE_DATE2" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"label" : "Close Date (2)"

},

"CLOSE_MONTH" : {

"dataType" : "date",

8

Create a New Report

Examples: Reports REST API Resources

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Close Month"

"LAST_STAGE_CHANGE_DATE" : {

"dataType" : "datetime",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Last Stage Change Date"

"NEXT_STEP" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Next Step"

},

"STAGE_NAME" : {

"dataType" : "picklist",

"filterValues" : [ {

"label" : "Prospecting",

"name" : "Prospecting"

}, {

"label" : "Qualification",

"name" : "Qualification"

}, {

"label" : "Needs Analysis",

"name" : "Needs Analysis"

}, {

"label" : "Value Proposition",

"name" : "Value Proposition"

}, {

"label" : "Id. Decision Makers",

"name" : "Id. Decision Makers"

}, {

"label" : "Perception Analysis",

"name" : "Perception Analysis"

}, {

"label" : "Proposal/Price Quote",

"name" : "Proposal/Price Quote"

}, {

"label" : "Negotiation/Review",

"name" : "Negotiation/Review"

}, {

"label" : "Closed Won",

"name" : "Closed Won"

}, {

"label" : "Closed Lost",

"name" : "Closed Lost"

} ],

"filterable" : true,

"label" : "Stage"

},

"PROBABILITY" : {

"dataType" : "percent",

9

Create a New Report

Examples: Reports REST API Resources

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Probability (%)"

"FISCAL_QUARTER" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Fiscal Period"

"FISCAL_YEAR" : {

"dataType" : "int",

"filterValues" : [ ],

"filterable" : true,

"label" : "Fiscal Year"

},

"AGE" : {

"dataType" : "int",

"filterValues" : [ ],

"filterable" : true,

"label" : "Age"

},

"STAGE_DURATION" : {

"dataType" : "int",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Stage Duration"

"FORECAST_CATEGORY" : {

"dataType" : "picklist",

"filterValues" : [ {

"label" : "Omitted",

"name" : "Omitted"

}, {

"label" : "Pipeline",

"name" : "Pipeline"

}, {

"label" : "Best Case",

"name" : "Best Case"

}, {

"label" : "Commit",

"name" : "Commit"

}, {

"label" : "Closed",

"name" : "Closed"

} ],

"filterable" : true,

"label" : "Forecast Category"

},

"OPPORTUNITY_ID" : {

"dataType" : "id",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity ID"

10

Create a New Report

Examples: Reports REST API Resources

},

"LAST_ACTIVITY" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"label" : "Last Activity"

},

"DESCRIPTION" : {

"dataType" : "textarea",

"filterValues" : [ ],

"filterable" : true,

"label" : "Description"

},

"HASOPPLINEITEM" : {

"dataType" : "boolean",

"filterValues" : [ {

"label" : "True",

"name" : "True"

}, {

"label" : "False",

"name" : "False"

} ],

"filterable" : true,

"label" : "Has Products"

},

"CREATED_DATE" : {

"dataType" : "datetime",

"filterValues" : [ ],

"filterable" : true,

"label" : "Created Date"

},

"LAST_UPDATE" : {

"dataType" : "datetime",

"filterValues" : [ ],

"filterable" : true,

"label" : "Last Modified Date"

}

},

"label" : "Opportunity Information"

}, {

"columns" : {

"FULL_NAME" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner"

},

"ROLLUP_DESCRIPTION" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Owner Role"

},

"ALIAS" : {

11

Create a New Report

Examples: Reports REST API Resources

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner Alias"

},

"OWNER_EMAIL" : {

"dataType" : "email",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner Email"

},

"OWNER_PHONE" : {

"dataType" : "phone",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Opportunity Owner: Phone"

"OWNER_MOBILE_PHONE" : {

"dataType" : "phone",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner: Mobile Phone"

},

"OWNER_MANAGER" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner: Manager"

},

"OWNER_TITLE" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Opportunity Owner: Title"

"OWNER_COMPANY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Opportunity Owner: Company"

"OWNER_DEPARTMENT" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner: Department"

},

"OWNER_DIVISION" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner: Division"

},

"OWNER_PROFILE" : {

12

Create a New Report

Examples: Reports REST API Resources

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Opportunity Owner: Profile"

},

"OWNER_ACTIVE" : {

"dataType" : "boolean",

"filterValues" : [ {

"label" : "True",

"name" : "True"

}, {

"label" : "False",

"name" : "False"

} ],

"filterable" : true,

"label" : "Opportunity Owner: Active"

}

},

"label" : "Opportunity Owner Information"

}, {

"columns" : {

"ACCOUNT_NAME" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Account Name"

},

"ACCOUNT_OWNER" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Account Owner"

},

"ACCOUNT_OWNER_ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Account Owner Alias"

"PARENT_NAME" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Parent Account"

},

"PARENT_ID" : {

"dataType" : "id",

"filterValues" : [ ],

"filterable" : true,

"label" : "Parent Account ID"

},

"SALES" : {

"dataType" : "currency",

"filterValues" : [ ],

13

Create a New Report

Examples: Reports REST API Resources

"filterable" : true,

"label" : "Annual Revenue"

},

"ACCOUNT_TYPE" : {

"dataType" : "picklist",

"filterValues" : [ {

"label" : "Analyst",

"name" : "Analyst"

}, {

"label" : "Competitor",

"name" : "Competitor"

}, {

"label" : "Customer",

"name" : "Customer"

}, {

"label" : "Integrator",

"name" : "Integrator"

}, {

"label" : "Investor",

"name" : "Investor"

}, {

"label" : "Partner",

"name" : "Partner"

}, {

"label" : "Press",

"name" : "Press"

}, {

"label" : "Prospect",

"name" : "Prospect"

}, {

"label" : "Reseller",

"name" : "Reseller"

}, {

"label" : "Other",

"name" : "Other"

} ],

"filterable" : true,

},

"label" : "Account Type"

"INDUSTRY" : {

"dataType" : "picklist",

"filterValues" : [ {

"label" : "Agriculture",

"name" : "Agriculture"

}, {

"label" : "Apparel",

"name" : "Apparel"

}, {

"label" : "Banking",

"name" : "Banking"

}, {

"label" : "Biotechnology",

"name" : "Biotechnology"

}, {

14

Create a New Report

Examples: Reports REST API Resources

"label" : "Chemicals",

"name" : "Chemicals"

}, {

"label" : "Communications",

"name" : "Communications"

}, {

"label" : "Construction",

"name" : "Construction"

}, {

"label" : "Consulting",

"name" : "Consulting"

}, {

"label" : "Education",

"name" : "Education"

}, {

"label" : "Electronics",

"name" : "Electronics"

}, {

"label" : "Energy",

"name" : "Energy"

}, {

"label" : "Engineering",

"name" : "Engineering"

}, {

"label" : "Entertainment",

"name" : "Entertainment"

}, {

"label" : "Environmental",

"name" : "Environmental"

}, {

"label" : "Finance",

"name" : "Finance"

}, {

"label" : "Food & Beverage",

"name" : "Food & Beverage"

}, {

"label" : "Government",

"name" : "Government"

}, {

"label" : "Healthcare",

"name" : "Healthcare"

}, {

"label" : "Hospitality",

"name" : "Hospitality"

}, {

"label" : "Insurance",

"name" : "Insurance"

}, {

"label" : "Machinery",

"name" : "Machinery"

}, {

"label" : "Manufacturing",

"name" : "Manufacturing"

}, {

15

Create a New Report

Examples: Reports REST API Resources

"label" : "Media",

"name" : "Media"

}, {

"label" : "Not For Profit",

"name" : "Not For Profit"

}, {

"label" : "Other",

"name" : "Other"

}, {

"label" : "Recreation",

"name" : "Recreation"

}, {

"label" : "Retail",

"name" : "Retail"

}, {

"label" : "Shipping",

"name" : "Shipping"

}, {

"label" : "Technology",

"name" : "Technology"

}, {

"label" : "Telecommunications",

"name" : "Telecommunications"

}, {

"label" : "Transportation",

"name" : "Transportation"

}, {

"label" : "Utilities",

"name" : "Utilities"

} ],

"filterable" : true,

"label" : "Industry"

},

"EMPLOYEES" : {

"dataType" : "int",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Employees"

"ACCOUNT_ID" : {

"dataType" : "id",

"filterValues" : [ ],

"filterable" : true,

"label" : "Account ID"

},

"ACCOUNT_LAST_ACTIVITY" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"label" : "Account: Last Activity"

},

"ACCOUNT_CREATED_DATE" : {

"dataType" : "datetime",

"filterValues" : [ ],

16

Create a New Report

Examples: Reports REST API Resources

"filterable" : true,

"label" : "Account: Created Date"

},

"ACCOUNT_LAST_UPDATE" : {

"dataType" : "datetime",

"filterValues" : [ ],

"filterable" : true,

"label" : "Account: Last Modified Date"

},

"ACCOUNT_DESCRIPTION" : {

"dataType" : "textarea",

"filterValues" : [ ],

"filterable" : true,

"label" : "Account Description"

}

},

"label" : "Account: General"

}, {

"columns" : {

"ADDRESS1_STREET" : {

"dataType" : "textarea",

"filterValues" : [ ],

"filterable" : true,

"label" : "Billing Street"

},

"ADDRESS1_LINE1" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Billing Address Line 1"

},

"ADDRESS1_LINE2" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Billing Address Line 2"

"ADDRESS1_LINE3" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Billing Address Line 3"

},

"ADDRESS1_CITY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Billing City"

},

"ADDRESS1_STATE" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Billing State/Province"

17

Create a New Report

Examples: Reports REST API Resources

},

"ADDRESS1_ZIP" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Billing Zip/Postal Code"

},

"ADDRESS1_COUNTRY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Billing Country"

},

"ADDRESS2_STREET" : {

"dataType" : "textarea",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Shipping Street"

"ADDRESS2_LINE1" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Shipping Address Line 1"

},

"ADDRESS2_LINE2" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Shipping Address Line 2"

},

"ADDRESS2_LINE3" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Shipping Address Line 3"

"ADDRESS2_CITY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Shipping City"

},

"ADDRESS2_STATE" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Shipping State/Province"

},

"ADDRESS2_ZIP" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Shipping Zip/Postal Code"

18

Create a New Report

Examples: Reports REST API Resources

},

"ADDRESS2_COUNTRY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Shipping Country"

},

}

"label" : "Account: Address"

}, {

"columns" : {

"PHONE1" : {

"dataType" : "phone",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Phone"

"PHONE2" : {

"dataType" : "phone",

"filterValues" : [ ],

"filterable" : true,

"label" : "Fax"

},

"URL" : {

"dataType" : "url",

"filterValues" : [ ],

"filterable" : true,

"label" : "Website"

},

}

"label" : "Account: Ph/Fax"

}, {

"columns" : {

"CONTACT" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Primary Contact"

"CON.TITLE" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Contact: Title"

},

"CON.PHONE" : {

"dataType" : "phone",

"filterValues" : [ ],

"filterable" : true,

"label" : "Contact: Phone"

},

"CON.EMAIL" : {

"dataType" : "email",

"filterValues" : [ ],

19

Create a New Report

Examples: Reports REST API Resources

"filterable" : true,

"label" : "Contact: Email"

},

}

"label" : "Primary Contact"

}, {

"columns" : {

"CON.ADDRESS2_STREET" : {

"dataType" : "textarea",

"filterValues" : [ ],

"filterable" : true,

"label" : "Mailing Street"

},

"CON.ADDRESS2_LINE1" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Mailing Address Line 1"

"CON.ADDRESS2_LINE2" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Mailing Address Line 2"

},

"CON.ADDRESS2_LINE3" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Mailing Address Line 3"

},

"CON.ADDRESS2_CITY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Mailing City"

"CON.ADDRESS2_STATE" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Mailing State/Province"

},

"CON.ADDRESS2_ZIP" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Mailing Zip/Postal Code"

},

"CON.ADDRESS2_COUNTRY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Mailing Country"

20

Create a New Report

Examples: Reports REST API Resources

},

"CON.ADDRESS1_STREET" : {

"dataType" : "textarea",

"filterValues" : [ ],

"filterable" : true,

"label" : "Other Street"

},

"CON.ADDRESS1_LINE1" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Other Address Line 1"

},

"CON.ADDRESS1_LINE2" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Other Address Line 2"

"CON.ADDRESS1_LINE3" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Other Address Line 3"

},

"CON.ADDRESS1_CITY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Other City"

},

"CON.ADDRESS1_STATE" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

},

"label" : "Other State/Province"

"CON.ADDRESS1_ZIP" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Other Zip/Postal Code"

},

"CON.ADDRESS1_COUNTRY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"label" : "Other Country"

},

}

"label" : "Contact: Address"

} ],

"dataTypeFilterOperatorMap" : {

"date" : [ {

21

Create a New Report

Examples: Reports REST API Resources

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"string" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"picklist" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

22

Create a New Report

Examples: Reports REST API Resources

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"textarea" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"percent" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

23

Create a New Report

Examples: Reports REST API Resources

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"int" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"url" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

24

Create a New Report

Examples: Reports REST API Resources

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"datetime" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"boolean" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

} ],

"phone" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

25

Create a New Report

Examples: Reports REST API Resources

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"currency" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"id" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"email" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

26

Create a New Report

Examples: Reports REST API Resources

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

},

} ]

"divisionInfo" : null,

"scopeInfo" : {

"defaultValue" : "organization",

"values" : [ {

"allowsDivision" : false,

"label" : "My opportunities",

"value" : "user"

}, {

"allowsDivision" : false,

"label" : "My team's opportunities",

"value" : "team"

}, {

"allowsDivision" : true,

"label" : "All opportunities",

"value" : "organization"

} ]

},

"standardDateFilterDurationGroups" : [ {

"label" : "",

"standardDateFilterDurations" : [ {

"endDate" : "2016-12-12",

"label" : "Custom",

"startDate" : "2016-12-13",

"value" : "CUSTOM"

} ]

}, {

"label" : "Fiscal Year",

"standardDateFilterDurations" : [ {

"endDate" : "2016-12-31",

"label" : "Current FY",

"startDate" : "2016-01-01",

"value" : "THIS_FISCAL_YEAR"

}, {

"endDate" : "2015-12-31",

"label" : "Previous FY",

"startDate" : "2015-01-01",

"value" : "LAST_FISCAL_YEAR"

}, {

"endDate" : "2015-12-31",

"label" : "Previous 2 FY",

"startDate" : "2014-01-01",

"value" : "LAST_N_FISCAL_YEARS:2"

}, {

"endDate" : "2014-12-31",

27

Create a New Report

Examples: Reports REST API Resources

"label" : "2 FY Ago",

"startDate" : "2014-01-01",

"value" : "LAST_N_FISCAL_YEARS_AGO:2"

}, {

"endDate" : "2017-12-31",

"label" : "Next FY",

"startDate" : "2017-01-01",

"value" : "NEXT_FISCAL_YEAR"

}, {

"endDate" : "2016-12-31",

"label" : "Current and Previous FY",

"startDate" : "2015-01-01",

"value" : "THIS_AND_LAST_FISCAL_YEAR:2"

}, {

"endDate" : "2016-12-31",

"label" : "Current and Previous 2 FY",

"startDate" : "2014-01-01",

"value" : "THIS_AND_LAST_N_FISCAL_YEARS:2"

}, {

"endDate" : "2017-12-31",

"label" : "Current and Next FY",

"startDate" : "2016-01-01",

"value" : "THIS_AND_NEXT_FISCAL_YEAR"

} ]

}, {

"label" : "Fiscal Quarter",

"standardDateFilterDurations" : [ {

"endDate" : "2016-12-31",

"label" : "Current FQ",

"startDate" : "2016-10-01",

"value" : "THIS_FISCAL_QUARTER"

}, {

"endDate" : "2017-03-31",

"label" : "Current and Next FQ",

"startDate" : "2016-10-01",

"value" : "THIS_AND_NEXT_FISCAL_QUARTER"

}, {

"endDate" : "2016-12-31",

"label" : "Current and Previous FQ",

"startDate" : "2016-07-01",

"value" : "LAST_AND_THIS_FISCAL_QUARTER"

}, {

"endDate" : "2017-03-31",

"label" : "Next FQ",

"startDate" : "2017-01-01",

"value" : "NEXT_FISCAL_QUARTER"

}, {

"endDate" : "2016-09-30",

"label" : "Previous FQ",

"startDate" : "2016-07-01",

"value" : "LAST_FISCAL_QUARTER"

}, {

"endDate" : "2017-09-30",

"label" : "Current and Next 3 FQ",

28

Create a New Report

Examples: Reports REST API Resources

} ]

}, {

"startDate" : "2016-10-01",

"value" : "THIS_AND_NEXT_N_FISCAL_QUARTERS:3"

"label" : "Calendar Year",

"standardDateFilterDurations" : [ {

"endDate" : "2016-12-31",

"label" : "Current CY",

"startDate" : "2016-01-01",

"value" : "THIS_YEAR"

}, {

"endDate" : "2015-12-31",

"label" : "Previous CY",

"startDate" : "2015-01-01",

"value" : "LAST_YEAR"

}, {

"endDate" : "2015-12-31",

"label" : "Previous 2 CY",

"startDate" : "2014-01-01",

"value" : "LAST_N_YEARS:2"

}, {

"endDate" : "2014-12-31",

"label" : "2 CY Ago",

"startDate" : "2014-01-01",

"value" : "LAST_N_YEARS_AGO:2"

}, {

"endDate" : "2017-12-31",

"label" : "Next CY",

"startDate" : "2017-01-01",

"value" : "NEXT_YEAR"

}, {

"endDate" : "2016-12-31",

"label" : "Current and Previous CY",

"startDate" : "2015-01-01",

"value" : "THIS_AND_LAST_YEAR:2"

}, {

"endDate" : "2016-12-31",

"label" : "Current and Previous 2 CY",

"startDate" : "2014-01-01",

"value" : "THIS_AND_LAST_N_YEARS:2"

}, {

"endDate" : "2017-12-31",

"label" : "Current and Next CY",

"startDate" : "2016-01-01",

"value" : "THIS_AND_NEXT_YEAR"

} ]

}, {

"label" : "Calendar Quarter",

"standardDateFilterDurations" : [ {

"endDate" : "2016-12-31",

"label" : "Current CQ",

"startDate" : "2016-10-01",

"value" : "THIS_QUARTER"

}, {

29

Create a New Report

Examples: Reports REST API Resources

"endDate" : "2017-03-31",

"label" : "Current and Next CQ",

"startDate" : "2016-10-01",

"value" : "THIS_AND_NEXT_QUARTER"

}, {

"endDate" : "2016-12-31",

"label" : "Current and Previous CQ",

"startDate" : "2016-07-01",

"value" : "LAST_AND_THIS_QUARTER"

}, {

"endDate" : "2017-03-31",

"label" : "Next CQ",

"startDate" : "2017-01-01",

"value" : "NEXT_QUARTER"

}, {

"endDate" : "2016-09-30",

"label" : "Previous CQ",

"startDate" : "2016-07-01",

"value" : "LAST_QUARTER"

}, {

"endDate" : "2017-09-30",

"label" : "Current and Next 3 CQ",

"startDate" : "2016-10-01",

"value" : "THIS_AND_NEXT_N_QUARTERS:3"

} ]

}, {

"label" : "Calendar Month",

"standardDateFilterDurations" : [ {

"endDate" : "2016-11-30",

"label" : "Last Month",

"startDate" : "2016-11-01",

"value" : "LAST_MONTH"

}, {

"endDate" : "2016-12-31",

"label" : "This Month",

"startDate" : "2016-12-01",

"value" : "THIS_MONTH"

}, {

"endDate" : "2017-01-31",

"label" : "Next Month",

"startDate" : "2017-01-01",

"value" : "NEXT_MONTH"

}, {

"endDate" : "2016-12-31",

"label" : "Current and Previous Month",

"startDate" : "2016-11-01",

"value" : "LAST_AND_THIS_MONTH"

}, {

"endDate" : "2017-01-31",

"label" : "Current and Next Month",

"startDate" : "2016-12-01",

"value" : "THIS_AND_NEXT_MONTH"

} ]

}, {

30

Create a New Report

Examples: Reports REST API Resources

"label" : "Calendar Week",

"standardDateFilterDurations" : [ {

"endDate" : "2016-12-10",

"label" : "Last Week",

"startDate" : "2016-12-04",

"value" : "LAST_WEEK"

}, {

"endDate" : "2016-12-17",

"label" : "This Week",

"startDate" : "2016-12-11",

"value" : "THIS_WEEK"

}, {

"endDate" : "2016-12-24",

"label" : "Next Week",

"startDate" : "2016-12-18",

"value" : "NEXT_WEEK"

} ]

}, {

"label" : "Day",

"standardDateFilterDurations" : [ {

"endDate" : "2016-12-12",

"label" : "Yesterday",

"startDate" : "2016-12-12",

"value" : "YESTERDAY"

}, {

"endDate" : "2016-12-13",

"label" : "Today",

"startDate" : "2016-12-13",

"value" : "TODAY"

}, {

"endDate" : "2016-12-14",

"label" : "Tomorrow",

"startDate" : "2016-12-14",

"value" : "TOMORROW"

}, {

"endDate" : "2016-12-13",

"label" : "Last 7 Days",

"startDate" : "2016-12-07",

"value" : "LAST_N_DAYS:7"

}, {

"endDate" : "2016-12-13",

"label" : "Last 30 Days",

"startDate" : "2016-11-14",

"value" : "LAST_N_DAYS:30"

}, {

"endDate" : "2016-12-13",

"label" : "Last 60 Days",

"startDate" : "2016-10-15",

"value" : "LAST_N_DAYS:60"

}, {

"endDate" : "2016-12-13",

"label" : "Last 90 Days",

"startDate" : "2016-09-15",

"value" : "LAST_N_DAYS:90"

31

Create a New Report

Examples: Reports REST API Resources

}, {

"endDate" : "2016-12-13",

"label" : "Last 120 Days",

"startDate" : "2016-08-16",

"value" : "LAST_N_DAYS:120"

}, {

"endDate" : "2016-12-19",

"label" : "Next 7 Days",

"startDate" : "2016-12-13",

"value" : "NEXT_N_DAYS:7"

}, {

"endDate" : "2017-01-11",

"label" : "Next 30 Days",

"startDate" : "2016-12-13",

"value" : "NEXT_N_DAYS:30"

}, {

"endDate" : "2017-02-10",

"label" : "Next 60 Days",

"startDate" : "2016-12-13",

"value" : "NEXT_N_DAYS:60"

}, {

"endDate" : "2017-03-12",

"label" : "Next 90 Days",

"startDate" : "2016-12-13",

"value" : "NEXT_N_DAYS:90"

}, {

"endDate" : "2017-04-11",

"label" : "Next 120 Days",

"startDate" : "2016-12-13",

"value" : "NEXT_N_DAYS:120"

} ]

} ],

"standardFilterInfos" : {

"probability" : {

"type" : "PICKLIST",

"filterValues" : [ {

"label" : "All",

"name" : ">0"

}, {

"label" : "> 90%",

"name" : "gt90"

}, {

"label" : "> 80%",

"name" : "gt80"

}, {

"label" : "> 70%",

"name" : "gt70"

}, {

"label" : "> 60%",

"name" : "gt60"

}, {

"label" : "> 50%",

"name" : "gt50"

}, {

32

Create a New Report

Examples: Reports REST API Resources

"label" : "> 40%",

"name" : "gt40"

}, {

"label" : "> 30%",

"name" : "gt30"

}, {

"label" : "> 20%",

"name" : "gt20"

}, {

"label" : "> 10%",

"name" : "gt10"

}, {

"label" : "< 90%",

"name" : "lt90"

}, {

"label" : "< 80%",

"name" : "lt80"

}, {

"label" : "< 70%",

"name" : "lt70"

}, {

"label" : "< 60%",

"name" : "lt60"

}, {

"label" : "< 50%",

"name" : "lt50"

}, {

"label" : "< 40%",

"name" : "lt40"

}, {

"label" : "< 30%",

"name" : "lt30"

}, {

"label" : "< 20%",

"name" : "lt20"

}, {

"label" : "< 10%",

"name" : "lt10"

} ],

},

"label" : "Probability"

"open" : {

"type" : "PICKLIST",

"filterValues" : [ {

"label" : "Any",

"name" : "all"

}, {

"label" : "Open",

"name" : "open"

}, {

"label" : "Closed",

"name" : "closed"

}, {

"label" : "Closed Won",

33

Create a New Report

Examples: Reports REST API Resources Run Reports Synchronously or Asynchronously

}

}

}

}

"name" : "closedwon"

} ],

"label" : "Opportunity Status"

Run Reports Synchronously or Asynchronously

Get summary data with or without details by running a report synchronously or asynchronously through the API. When you run a report, the API returns data for the same number of records that are available when the report is run in the Salesforce user interface.

Run a report synchronously if you expect it to finish running quickly. Otherwise, we recommend that you run reports through the API asynchronously for these reasons:

•

Long running reports have a lower risk of reaching the timeout limit when run asynchronously.

•

The 2-minute overall Salesforce API timeout limit doesn’t apply to asynchronous runs.

•

The Salesforce Reports and Dashboards REST API can handle a higher number of asynchronous run requests at a time.

•

Since the results of an asynchronously run report are stored for a 24-hr rolling period, they’re available for recurring access.

To run a report synchronously:

•

Send a GET or POST request to the Execute Sync resource to get data.

•

Use a POST request to get specific results on the fly by passing dynamic filters, groupings, and aggregates in the report metadata.

To fetch report data asynchronously:

1. Send a POST request to the Execute Async resource. If you’re passing filters, include them in the POST request metadata. The request returns the instance ID where results of the run are stored.

2. Send a GET request to the Instance Results resource to fetch data using the instance ID.

Example of a synchronous report run

This GET request to the Execute Sync resource,

/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK?includeDetails=true

, for a synchronous run returns summary data with details.

{

"attributes" : {

"describeUrl" :

"/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/describe",

"instancesUrl" :

"/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances",

"reportId" :

"00OR0000000K2UeMAK",

"reportName" : "Deals Closing This Quarter",

"type" : "Report"

},

"allData" : true,

"factMap" : {

"2!0_0" : {

34

Examples: Reports REST API Resources Run Reports Synchronously or Asynchronously

"aggregates" : [

{ "label" : "$16,000.01", "value" : 16000.010000000000218278728425502777099609375

},

{ "label" : "$16,000.01", "value" : 16000.010000000000218278728425502777099609375

},

{ "label" : "1", "value" : 1 } ],

"rows" : [ {

"dataCells" : [

{ "label" : "Acme - 200 Widgets", "value" : "006R00000023IDYIA2" },

{ "label" : "$16,000.01",

"value" : { "amount" : 16000.01, "currency" : null } },

{ "label" : "Word of mouth", "value" : "Word of mouth" },

{ "label" : "Need estimate", "value" : "Need estimate" },

{ "label" : "60%", "value" : 60},

{ "label" : "Q3-2015", "value" : "Q3-2015" },

{ "label" : "12", "value" : 12 },

{ "label" : "7/31/2015", "value" : "2015-07-31" },

{ "label" : "Fred Wiliamson", "value" : "005R0000000Hv5rIAC" },

{ "label" : "-", "value" : null } ]

} ]

},

"T!0" : {

"aggregates" : [

{ "label" : "$32,021.01", "value" : 32021.00999999999839928932487964630126953125

},

{ "label" : "$16,010.51", "value" : 16010.504999999999199644662439823150634765625

},

},

{ "label" : "2", "value" : 2 } ],

"rows" : [ ]

...

"T!T" : {

"aggregates" : [

{ "label" : "$153,042.01", "value" : 153042.01000000000931322574615478515625 },

{ "label" : "$25,507.00", "value" : 25507.00166666666700621135532855987548828125

},

{ "label" : "6", "value" : 6 } ],

"rows" : [ ]

},

...

"groupingsAcross" : {

"groupings" : [

{

"groupings" : [

{ "groupings" : [ ], "key" : "0_0", "label" : "Existing Business", "value" :

"Existing Business" } ],

"key" : "0",

"label" : "July 2015",

},

"value" : "2015-07-01"

{

"groupings" : [

{ "groupings" : [ ], "key" : "1_0", "label" : "Existing Business", "value" :

"Existing Business" },

35

Examples: Reports REST API Resources Run Reports Synchronously or Asynchronously

{ "groupings" : [ ], "key" : "1_1", "label" : "New Business", "value" : "New

Business" } ],

"key" : "1",

"label" : "August 2015",

},

"value" : "2015-08-01"

{

"groupings" : [

{ "groupings" : [ ], "key" : "2_0", "label" : "Existing Business", "value" :

"Existing Business" } ],

"key" : "2",

"label" : "September 2015",

"value" : "2015-09-01"

}

]

},

"groupingsDown" : {

"groupings" : [

{ "groupings" : [ ], "key" : "0", "label" : "Acme", "value" : "001R0000002GuzsIAC"

},

{ "groupings" : [ ], "key" : "1", "label" : "Facebook", "value" : "001R0000001nUAmIAM"

},

{ "groupings" : [ ], "key" : "2", "label" : "Home Depot", "value" :

"001R0000002Gv5zIAC" },

{ "groupings" : [ ], "key" : "3", "label" : "Mircosoft", "value" : "001R0000002Gv5QIAS"

} ]

},

"hasDetailRows" : true,

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"s!AMOUNT" : {

"acrossGroupingContext" : null,

"dataType" : "currency",

"downGroupingContext" : null,

"label" : "Sum of Amount" },

"a!AMOUNT" : {

"acrossGroupingContext" : null,

"dataType" : "currency",

"downGroupingContext" : null,

"label" : "Average Amount" },

"RowCount" : {

"acrossGroupingContext" : null,

"dataType" : "int",

"downGroupingContext" : null,

"label" : "Record Count" }

},

"detailColumnInfo" : {

"OPPORTUNITY_NAME" : { "dataType" : "string", "label" : "Opportunity Name" },

"AMOUNT" : { "dataType" : "currency", "label" : "Amount" },

"LEAD_SOURCE" : { "dataType" : "picklist", "label" : "Lead Source" },

"NEXT_STEP" : { "dataType" : "string", "label" : "Next Step" },

"PROBABILITY" : { "dataType" : "percent", "label" : "Probability (%)" },

"FISCAL_QUARTER" : { "dataType" : "string", "label" : "Fiscal Period" },

36

Examples: Reports REST API Resources Run Reports Synchronously or Asynchronously

"AGE" : { "dataType" : "int", "label" : "Age" },

"CREATED_DATE" : { "dataType" : "datetime", "label" : "Created Date" },

"FULL_NAME" : { "dataType" : "string", "label" : "Opportunity Owner" },

"ROLLUP_DESCRIPTION" : { "dataType" : "string", "label" : "Owner Role" }

},

"groupingColumnInfo" : {

"ACCOUNT_NAME" : { "dataType" : "string", "groupingLevel" : 0, "label" : "Account

Name" },

"CLOSE_DATE" : { "dataType" : "date", "groupingLevel" : 0, "label" : "Close Date"

},

"TYPE" : { "dataType" : "picklist", "groupingLevel" : 1, "label" : "Type" }

},

}

"reportMetadata" : {

"aggregates" : [ "s!AMOUNT", "a!AMOUNT", "RowCount" ],

"chart" : {

"chartType" : "Donut",

"groupings" : [ "CLOSE_DATE" ],

"hasLegend" : true,

"showChartValues" : false,

"summaries" : [ "s!AMOUNT" ],

"summaryAxisLocations" : [ "Y" ],

},

"title" : "Pipeline by Stage and Type"

"currency" : null,

"description" : null,

"detailColumns" : [ "OPPORTUNITY_NAME", "AMOUNT", "LEAD_SOURCE","NEXT_STEP",

"PROBABILITY", "FISCAL_QUARTER", "AGE", "CREATED_DATE", "FULL_NAME",

"ROLLUP_DESCRIPTION" ],

"developerName" : "Deals_Closing_This_Quarter",

"division" : null,

"folderId" : "00lR0000000M8IiIAK",

"groupingsAcross" : [

{ "dateGranularity" : "Month", "name" : "CLOSE_DATE", "sortAggregate" : null,

"sortOrder" : "Asc"},

{ "dateGranularity" : "None", "name" : "TYPE", "sortAggregate" : null, "sortOrder"

: "Asc" } ],

"groupingsDown" : [

{ "dateGranularity" : "None", "name" : "ACCOUNT_NAME", "sortAggregate" : null,

"sortOrder" : "Asc" } ],

"hasDetailRows" : true,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OR0000000K2UeMAK",

"name" : "Deals Closing This Quarter",

"reportBooleanFilter" : null,

"reportFilters" : [

{ "column" : "BucketField_36625466", "isRunPageEditable" : true, "operator" : "equals",

"value" : "Early,Late" },

{ "column" : "TYPE", "isRunPageEditable" : true, "operator" : "equals", "value" :

"Existing Business,New Business" } ],

"reportFormat" : "MATRIX",

"reportType" : { "label" : "Opportunities", "type" : "Opportunity" },

"scope" : "organization",

37

Examples: Reports REST API Resources Run Reports Synchronously or Asynchronously

}

}

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CLOSE_DATE",

"durationValue" : "THIS_FISCAL_QUARTER",

"endDate" : "2015-09-30",

"startDate" : "2015-07-01" },

"standardFilters" : [

{ "name" : "open", "value" : "all" },

{ "name" : "probability", "value" : ">0" } ]

Example of an asynchronous report run

1. This is a POST request (an empty request body),

/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances

, to the Execute Async resource for an asynchronous run requesting summary results.

{}

The response to the POST request returns the instance handle that stores the summary results of the run.

{

"completionDate" : null,

"hasDetailRows" : true,

"id" : "0LGR00000000He3OAE",

"ownerId" : "005R0000000Hv5rIAC",

"queryable" : false,

"requestDate" : "2015-08-12T16:05:43Z",

"status" : "New",

"url" :

"/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances/0LGR00000000He3OAE"

}

2. A GET request,

/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances/0LGR00000000He3OAE

, to the Instance Results resource for the instance handle fetches the report results.

{

"attributes" : {

"completionDate" : "2015-08-12T16:05:44Z",

"id" : "0LGR00000000He3OAE",

"ownerId" : "005R0000000Hv5rIAC",

"queryable" : false,

"reportId" : "00OR0000000K2UeMAK",

"reportName" : "Deals Closing This Quarter",

"requestDate" : "2015-08-12T16:05:43Z",

"status" : "Success",

"type" : "ReportInstance" },

"allData" : true,

"factMap" : {

"2!0_0" : {

38

Examples: Reports REST API Resources Run Reports Synchronously or Asynchronously

"aggregates" : [

{ "label" : "$16,000.01", "value" : 16000.010000000000218278728425502777099609375

},

{ "label" : "$16,000.01", "value" : 16000.010000000000218278728425502777099609375

},

{ "label" : "1", "value" : 1 } ],

"rows" : [ {

"dataCells" : [

{ "label" : "Acme - 200 Widgets", "value" : "006R00000023IDYIA2" },

{ "label" : "$16,000.01",

"value" : { "amount" : 16000.01,

"currency" : null } },

{ "label" : "Word of mouth", "value" : "Word of mouth" },

{ "label" : "Need estimate", "value" : "Need estimate" },

{ "label" : "60%", "value" : 60 },

{ "label" : "Q3-2015", "value" : "Q3-2015" },

{ "label" : "12", "value" : 12 },

{ "label" : "7/31/2015", "value" : "2015-07-31" },

{ "label" : "Fred Wiliamson", "value" : "005R0000000Hv5rIAC" },

},

...

"groupingsAcross" : {

"groupings" : [

...

{ "label" : "-", "value" : null } ]

} ]

},

]

"groupingsDown" : {

"groupings" : [

...

},

]

"hasDetailRows" : true,

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"s!AMOUNT" : {

"acrossGroupingContext" : null,

"dataType" : "currency",

"downGroupingContext" : null,

"label" : "Sum of Amount" },

"a!AMOUNT" : {

"acrossGroupingContext" : null,

"dataType" : "currency",

"downGroupingContext" : null,

"label" : "Average Amount" },

"RowCount" : {

"acrossGroupingContext" : null,

"dataType" : "int",

"downGroupingContext" : null,

"label" : "Record Count" }

},

"detailColumnInfo" :

{ "OPPORTUNITY_NAME" : { "dataType" : "string", "label" : "Opportunity Name" },

39

Examples: Reports REST API Resources Run Reports Synchronously or Asynchronously

"AMOUNT" : { "dataType" : "currency", "label" : "Amount"},

"LEAD_SOURCE" : { "dataType" : "picklist", "label" : "Lead Source" },

"NEXT_STEP" : { "dataType" : "string", "label" : "Next Step" },

"PROBABILITY" : { "dataType" : "percent", "label" : "Probability (%)" },

"FISCAL_QUARTER" : { "dataType" : "string", "label" : "Fiscal Period" },

"AGE" : { "dataType" : "int", "label" : "Age" },

"CREATED_DATE" : { "dataType" : "datetime", "label" : "Created Date" },

"FULL_NAME" : { "dataType" : "string", "label" : "Opportunity Owner" },

"ROLLUP_DESCRIPTION" : { "dataType" : "string", "label" : "Owner Role" } },

"groupingColumnInfo" : {

"ACCOUNT_NAME" : { "dataType" : "string", "groupingLevel" : 0, "label" : "Account

Name" },

"CLOSE_DATE" : { "dataType" : "date", "groupingLevel" : 0, "label" : "Close Date"

},

"TYPE" : { "dataType" : "picklist", "groupingLevel" : 1, "label" : "Type" }}

},

"reportMetadata" : {

"aggregates" : [ "s!AMOUNT", "a!AMOUNT", "RowCount" ],

"chart" : {

"chartType" : "Donut",

"groupings" : [ "CLOSE_DATE" ],

"hasLegend" : true,

"showChartValues" : false,

"summaries" : [ "s!AMOUNT" ],

"summaryAxisLocations" : [ "Y" ],

"title" : "Pipeline by Stage and Type" },

"currency" : null,

"description" : null,

"detailColumns" : [ "OPPORTUNITY_NAME", "AMOUNT", "LEAD_SOURCE", "NEXT_STEP",

"PROBABILITY",

"FISCAL_QUARTER", "AGE", "CREATED_DATE", "FULL_NAME", "ROLLUP_DESCRIPTION" ],

"developerName" : "Deals_Closing_This_Quarter",

"division" : null,

"folderId" : "00lR0000000M8IiIAK",

"groupingsAcross" : [

{ "dateGranularity" : "Month", "name" : "CLOSE_DATE", "sortAggregate" : null,

"sortOrder" : "Asc" },

{ "dateGranularity" : "None", "name" : "TYPE", "sortAggregate" : null, "sortOrder"

: "Asc" } ],

"groupingsDown" : [

{ "dateGranularity" : "None", "name" : "ACCOUNT_NAME", "sortAggregate" : null,

"sortOrder" : "Asc" } ],

"hasDetailRows" : true,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OR0000000K2UeMAK",

"name" : "Deals Closing This Quarter",

"reportBooleanFilter" : null,

"reportFilters" : [

{ "column" : "BucketField_36625466", "isRunPageEditable" : false, "operator" :

40

Examples: Reports REST API Resources Get Report Metadata

"equals", "value" : "Early,Late" },

{ "column" : "TYPE", "isRunPageEditable" : false, "operator" : "equals", "value"

: "Existing Business,New Business" } ],

"reportFormat" : "MATRIX",

"reportType" : { "label" : "Opportunities", "type" : "Opportunity" },

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CLOSE_DATE",

"durationValue" : "THIS_FISCAL_QUARTER",

"endDate" : "2015-09-30",

"startDate" : "2015-07-01" },

"standardFilters" : [

{ "name" : "open", "value" : "all" },

{ "name" : "probability", "value" : ">0" } ]

}

}

SEE ALSO:

Execute Sync

Instances List

Instance Results

Get Report Metadata

Report metadata gives information about a report and its report type. It includes information on fields used in the report for filters, groupings, detailed data, and summaries. You can use the metadata to do several things.

•

Find out what fields in the report type you can filter on and by what values.

•

Build custom chart visualizations using the metadata information on fields, groupings, detailed data, and summaries.

•

Change filters in the report metadata during a report run.

To get report metadata, send a GET request to the Describe resource.

Example

This GET request,

/services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/describe

, to the Describe resource returns metadata for a matrix report. This includes a bucket field, groupings, summaries, and a custom summary formula.

{

"reportTypeMetadata": {

"categories": [

{

"label": "Opportunity Information",

"columns": {

"CREATED": {

"filterValues": [],

"label": "Created By",

41

Examples: Reports REST API Resources

"dataType": "string",

"filterable": true

},

...

"TYPE": {

"filterValues": [

{

"name": "Add-On Business",

"label": "Add-On Business"

},

{

"name": "New Business",

"label": "New Business"

},

{

"name": "Services",

"label": "Services"

}

],

"label": "Type",

"dataType": "picklist",

"filterable": true

},

}

...

},

"reportExtendedMetadata": {

"detailColumnInfo": {

"OPPORTUNITY_NAME": {

"label": "Opportunity Name",

"dataType": "string"

},

"PROBABILITY": {

"label": "Probability (%)",

"dataType": "percent"

},

"EXP_AMOUNT": {

"label": "Expected Revenue",

"dataType": "currency"

},

"NEXT_STEP": {

},

"BucketField_34840671": {

"label": "Industry",

"dataType": "string"

}

"label": "Next Step",

"dataType": "string"

},

"aggregateColumnInfo": {

"RowCount": {

"label": "Record Count",

"dataType": "int",

"downGroupingContext": null,

42

Get Report Metadata

Examples: Reports REST API Resources

"acrossGroupingContext": null

},

"FORMULA1": {

"label": "formula1",

"dataType": "double",

"downGroupingContext": "ALL_SUMMARY_LEVELS",

"acrossGroupingContext": "ALL_SUMMARY_LEVELS"

},

"s!EXP_AMOUNT": {

"label": "Sum of Expected Revenue",

"dataType": "currency",

"downGroupingContext": null,

"acrossGroupingContext": null

}

},

"groupingColumnInfo": {

"CLOSE_DATE": {

"label": "Close Date",

"dataType": "date",

"groupingLevel": 1

},

"STAGE_NAME": {

"label": "Stage",

"dataType": "picklist",

"groupingLevel": 0

},

"ACCOUNT_NAME": {

"label": "Account Name",

"dataType": "string",

"groupingLevel": 0

},

"ACCOUNT_LAST_ACTIVITY": {

"label": "Account: Last Activity",

"dataType": "date",

"groupingLevel": 1

}

}

},

"reportMetadata": {

"name": "Stuck Opportunities",

"id": "00OD0000001ZbP7MAK",

"currency": null,

"developerName": "StuckOpportunities",

"groupingsDown": [

{

"name": "ACCOUNT_NAME",

"sortOrder": "Asc",

"dateGranularity": "None"

},

{

"name": "CLOSE_DATE",

"sortOrder": "Desc",

"dateGranularity": "FiscalQuarter"

}

43

Get Report Metadata

Examples: Reports REST API Resources

}

}

],

"groupingsAcross": [

{

"name": "STAGE_NAME",

"sortOrder": "Desc",

"dateGranularity": "None"

},

{

"name": "ACCOUNT_LAST_ACTIVITY",

"sortOrder": "Asc",

"dateGranularity": "Week"

}

],

"reportType": {

"type": "Opportunity",

"label": "Opportunities"

},

"aggregates": [

"s!EXP_AMOUNT",

"FORMULA1",

"RowCount"

],

"reportFormat": "MATRIX",

"reportBooleanFilter": null,

"reportFilters": [

{

"value": "Closed Won,Closed Lost",

"column": "STAGE_NAME",

"operator": "notEqual"

},

{

"value": "50",

"column": "PROBABILITY",

"operator": "greaterThan"

}

],

"detailColumns": [

"OPPORTUNITY_NAME",

"PROBABILITY",

"EXP_AMOUNT",

"NEXT_STEP",

"BucketField_34840671"

]

SEE ALSO:

Describe

Get a List of Report Types

Return a list of analytics notifications using a GET request.

44

Get a List of Report Types

Examples: Reports REST API Resources Get a List of Report Types

Use a GET request on the

Report Type List

resource to return a list of report types.

Example Usage

/services/data/v39.0/analytics/reportTypes

Example Response Body

[ {

"label" : "Accounts & Contacts",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountList",

"label" : "Accounts",

"type" : "AccountList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactList",

"label" : "Contacts & Accounts",

"type" : "ContactList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountPartner",

"label" : "Accounts with Partners",

"type" : "AccountPartner"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountTeam",

"label" : "Account with Account Teams",

"type" : "AccountTeam"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountContactRole",

"label" : "Accounts with Contact Roles",

"type" : "AccountContactRole"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountAsset",

"label" : "Accounts with Assets",

"type" : "AccountAsset"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactAsset",

"label" : "Contacts with Assets",

"type" : "ContactAsset"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountAuditHistory",

"label" : "Account History",

"type" : "AccountAuditHistory"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactAuditHistory",

} ]

}, {

"label" : "Contact History",

"type" : "ContactAuditHistory"

"label" : "Opportunities",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/Opportunity",

"label" : "Opportunities",

"type" : "Opportunity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityProduct",

"label" : "Opportunities with Products",

"type" : "OpportunityProduct"

45

Examples: Reports REST API Resources Get a List of Report Types

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityContact",

"label" : "Opportunities with Contact Roles",

"type" : "OpportunityContact"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityPartner",

"label" : "Opportunities with Partners",

"type" : "OpportunityPartner"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityCompetitor",

"label" : "Opportunities with Competitors",

"type" : "OpportunityCompetitor"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityHistory",

"label" : "Opportunity History",

"type" : "OpportunityHistory"

}, {

"describeUrl" :

"/services/data/v39.0/analytics/reportTypes/OpportunityFieldAuditHistory",

"label" : "Opportunity Field History",

"type" : "OpportunityFieldAuditHistory"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityTrend",

"label" : "Opportunity Trends",

"type" : "OpportunityTrend"

}, {

"describeUrl" :

"/services/data/v39.0/analytics/reportTypes/OpportunityContactProduct",

"label" : "Opportunities with Contact Roles and Products",

"type" : "OpportunityContactProduct"

} ]

}, {

"label" : "Customer Support Reports",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseList",

"label" : "Cases",

"type" : "CaseList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseHistory",

"label" : "Case Lifecycle",

"type" : "CaseHistory"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseContactRole",

"label" : "Cases with Contact Roles",

"type" : "CaseContactRole"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseAsset",

"label" : "Cases with Assets",

"type" : "CaseAsset"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseSolution",

"label" : "Cases with Solutions",

"type" : "CaseSolution"

46

Examples: Reports REST API Resources Get a List of Report Types

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseAuditHistory",

"label" : "Case History",

"type" : "CaseAuditHistory"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionList",

"label" : "Solutions",

"type" : "SolutionList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionCategory",

"label" : "Solution Categories",

"type" : "SolutionCategory"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionAuditHistory",

"label" : "Solution History",

"type" : "SolutionAuditHistory"

} ]

}, {

"label" : "Leads",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LeadList",

"label" : "Leads",

"type" : "LeadList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityLead",

"label" : "Leads with converted lead information",

"type" : "OpportunityLead"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LeadAuditHistory",

"label" : "Lead History",

"type" : "LeadAuditHistory"

} ]

}, {

"label" : "Activities",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/Activity",

"label" : "Tasks and Events",

"type" : "Activity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/EventAttendee",

"label" : "Events with Invitees",

"type" : "EventAttendee"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/EmailStatus",

"label" : "HTML Email Status",

"type" : "EmailStatus"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountActivity",

"label" : "Activities with Accounts",

"type" : "AccountActivity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactActivity",

"label" : "Activities with Contacts",

"type" : "ContactActivity"

47

Examples: Reports REST API Resources Get a List of Report Types

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityActivity",

"label" : "Activities with Opportunities",

"type" : "OpportunityActivity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LeadActivity",

"label" : "Activities with Leads",

"type" : "LeadActivity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseActivity",

"label" : "Activities with Cases",

"type" : "CaseActivity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionActivity",

"label" : "Activities with Solutions",

"type" : "SolutionActivity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractActivity",

"label" : "Activities with Contracts",

"type" : "ContractActivity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductActivity",

"label" : "Activities with Products",

"type" : "ProductActivity"

} ]

}, {

"label" : "Contracts and Orders",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractList",

"label" : "Contracts",

"type" : "ContractList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractAuditHistory",

"label" : "Contract History",

"type" : "ContractAuditHistory"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractOrder",

"label" : "Contracts with Orders",

"type" : "ContractOrder"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractOrderItem",

"label" : "Contracts with Orders and Products",

"type" : "ContractOrderItem"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractContactRole",

"label" : "Contracts with Contact Roles",

"type" : "ContractContactRole"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OrderList",

"label" : "Orders",

"type" : "OrderList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OrderItemList",

"label" : "Orders with Products",

48

Examples: Reports REST API Resources Get a List of Report Types

"type" : "OrderItemList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OrderAuditHistory",

"label" : "Order History",

"type" : "OrderAuditHistory"

} ]

}, {

"label" : "Price Books, Products and Assets",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductList",

"label" : "Products",

"type" : "ProductList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductOpportunity",

"label" : "Products with Opportunities",

"type" : "ProductOpportunity"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/PricebookProduct",

"label" : "Price Books with Products",

"type" : "PricebookProduct"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductAsset",

"label" : "Products with Assets",

"type" : "ProductAsset"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AssetWithProduct",

"label" : "Assets",

"type" : "AssetWithProduct"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AssetCase",

"label" : "Assets with Cases",

"type" : "AssetCase"

} ]

}, {

"label" : "Administrative Reports",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/User",

"label" : "Users",

"type" : "User"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ReportList",

"label" : "Reports",

"type" : "ReportList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/DocumentList",

"label" : "Documents",

"type" : "DocumentList"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LoginIpEmail",

"label" : "New Login Locations",

"type" : "LoginIpEmail"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/TwoFactorMethodsInfo",

"label" : "Identity Verification Methods",

49

Examples: Reports REST API Resources List Asynchronous Runs of a Report

"type" : "TwoFactorMethodsInfo"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CollabGroup",

"label" : "Collaboration Group Report",

"type" : "CollabGroup"

}, {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CollabGroupFeedPosts",

"label" : "Collaboration Group Feed Posts Report",

"type" : "CollabGroupFeedPosts"

} ]

}, {

"label" : "File and Content Reports",

"reportTypes" : [ {

"describeUrl" : "/services/data/v39.0/analytics/reportTypes/File",

"label" : "File and Content Report",

"type" : "File"

} ]

} ]

List Asynchronous Runs of a Report

You can get as many as 2000 instances of a report for which you requested asynchronous runs by sending a GET request to the Instances

List resource. The instance list is sorted by the date when the run was requested. Report results are stored for a rolling 24-hour period.

During this time, based on your user access level, you can access results for each instance of the report that was run.

Example

A GET request,

/services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/instances

, to the Instances

List resource returns two instances of the report that was run asynchronously. Each URL handle stores report results for that instance.

[

{

"id": "0LGD000000000IyOAI",

"requestDate": "2013-08-12T19:06:47Z",

"status": "Success",

"url":

"/services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/instances/0LGD000000000IyOAI",

"ownerId": "005D0000001KvxRIAS",

"queryable" : false,

"hasDetailRows": false,

"completionDate": "2013-08-12T19:06:48Z"

},

{

"id": "0LGD000000000IjOAI",

"requestDate": "2013-08-12T18:39:06Z",

"status": "Success",

"url":

"/services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/instances/0LGD000000000IjOAI",

"ownerId": "005D0000001KvxRIAS",

"queryable" : false,

50

Examples: Reports REST API Resources Filter Reports on Demand

]

}

"hasDetailRows": false,

"completionDate": "2013-08-12T18:39:07Z"

SEE ALSO:

Instances List

Filter Reports on Demand

To get specific results on the fly, filter reports through the API. Filter changes made through the API does not affect the source report definition. Using the API, you can filter with up to 20 custom field filters and add filter logic (such as AND, OR). But standard filters (such as range), filtering by row limit, and cross filters are unavailable.

Before you filter a report, it’s helpful to check these properties in the metadata that tell you if a field can be filtered, the values and criteria you can filter by, and filters that already exist in the report.

•

filterable

•

filterValues

•

dataTypeFilterOperatorMap

•

reportFilters

You can filter reports during synchronous or asynchronous report runs by making a POST request to the Execute Sync or Execute Async resource.

Example

In a POST request, an accounts report is filtered synchronously by these passing filters with filter logic in the metadata to the Execute

Sync resource.

1.

Account Name

not equal to Data Mart

2.

Account Owner

not equal to Admin User

3.

Annual Revenue

greater than "100,000"

4.

Industry

not equal to Manufacturing,Recreation

Filter logic: (1 OR 4) AND 2 AND 3.

{

"reportMetadata": {

"name": "FilterAcctsReport",

"id": "00OD0000001cw27MAA",

"reportFormat": "SUMMARY",

"reportBooleanFilter": "(1OR4)AND2AND3",

"reportFilters": [

{

"value": "DataMart",

"operator": "notEqual",

"column": "ACCOUNT.NAME"

},

{

51

Examples: Reports REST API Resources

}

}

"value": "AdminUser",

"operator": "notEqual",

"column": "USERS.NAME"

},

{

"value": "\"100,000\"",

"operator": "greaterThan",

"column": "SALES"

},

{

"value": "Manufacturing,Recreation",

"operator": "notEqual",

"column": "INDUSTRY"

}

],

"detailColumns": [

"RATING",

"LAST_UPDATE",

"SALES"

],

"developerName": "Filter_Accts_Report",

"reportType": {

"type": "AccountList",

"label": "Accounts"

},

"currency": null,

"aggregates": [

"s!SALES",

"RowCount"

],

"groupingsDown": [

{

"name": "USERS.NAME",

"sortAggregate": "s!SALES",

"sortOrder": "Desc",

"dateGranularity": "None"

},

{

"name": "ACCOUNT.NAME",

"sortAggregate": null,

"sortOrder": "Asc",

"dateGranularity": "None"

},

{

"name": "DUE_DATE",

"sortAggregate": null,

"sortOrder": "Asc",

"dateGranularity": "Month"

}

],

"groupingsAcross": []

52

Filter Reports on Demand

Examples: Reports REST API Resources Filter Reports on Demand

In response to the POST request, the report returns data that meets the given criteria.

{

"hasDetailRows": false,

"attributes": {

"describeUrl": "/services/data/v29.0/analytics/reports/00OD0000001cw27MAA/describe",

"instancesUrl":

"/services/data/v29.0/analytics/reports/00OD0000001cw27MAA/instances",

"type": "Report",

"reportName": "Filter Accts Report",

"reportId": "00OD0000001cw27MAA"

},

"factMap": {

"1_0!T": {

"aggregates": [

{

"value": 56000000,

"label": "$56,000,000"

},

{

"value": 1,

"label": "1"

}

]

},

"7_1!T": {

"aggregates": [

{

"value": 24000000,

"label": "$24,000,000"

},

{

"value": 1,

"label": "1"

}

]

},

...

"allData": true,

"reportMetadata": {

"name": "Filter Accts Report",

"id": "00OD0000001cw27MAA",

"reportFormat": "SUMMARY",

"reportBooleanFilter": "(1 OR 4) AND 2 AND 3",

"reportFilters": [

{

"value": "Data Mart",

"operator": "notEqual",

"column": "ACCOUNT.NAME"

},

{

"value": "Admin User",

"operator": "notEqual",

"column": "USERS.NAME"

53

Examples: Reports REST API Resources List Recently Viewed Reports

...

}

}

},

{

"value": "\"100,000\"",

"operator": "greaterThan",

"column": "SALES"

},

{

"value": "Manufacturing,Recreation",

"operator": "notEqual",

"column": "INDUSTRY"

}

],

"detailColumns": [

"RATING",

"LAST_UPDATE",

"SALES"

],

SEE ALSO:

Execute Sync

List Recently Viewed Reports

Get up to 200 of the reports you most recently viewed in Salesforce by sending a GET request to the Report List resource.

Each report listing in the response has resource URLs to get metadata and run a report asynchronously or synchronously.

For a more extensive reports list, query the Report object using a SOQL query in a Salesforce API such as SOAP API or REST API. This SOQL query, for example, returns all reports that are in matrix format:

SELECT Description,Format,LastRunDate FROM

Report WHERE Format = 'MATRIX' ORDER BY Id ASC NULLS FIRST

Example

This GET request

/services/data/v35.0/analytics/reports

to the Report List resource returns a list of 5 recently viewed reports.

[

{

"describeUrl" : "/services/data/v35.0/analytics/reports/00OR0000000K2OmMAK/describe",

"id" : "00OR0000000K2OmMAK",

"instancesUrl" : "/services/data/v35.0/analytics/reports/00OR0000000K2OmMAK/instances",

"name" : "Pipeline By Industry",

"url" : "/services/data/v35.0/analytics/reports/00OR0000000K2OmMAK" },

{

"describeUrl" : "/services/data/v35.0/analytics/reports/00OR0000000OFXeMAO/describe",

"id" : "00OR0000000OFXeMAO",

54

Examples: Reports REST API Resources Decode the Fact Map

"instancesUrl" : "/services/data/v35.0/analytics/reports/00OR0000000OFXeMAO/instances",

"name" : "My Open Pipeline",

"url" : "/services/data/v35.0/analytics/reports/00OR0000000OFXeMAO" },

{

"describeUrl" : "/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/describe",

"id" : "00OR0000000K2UeMAK",

"instancesUrl" : "/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances",

{

"name" : "Deals Closing This Quarter",

"url" : "/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK" },

"describeUrl" : "/services/data/v35.0/analytics/reports/00OR0000000OFHoMAO/describe",

]

"id" : "00OR0000000OFHoMAO",

"instancesUrl" : "/services/data/v35.0/analytics/reports/00OR0000000OFHoMAO/instances",

"name" : "Sample Report: # of Opportunities",

"url" : "/services/data/v35.0/analytics/reports/00OR0000000OFHoMAO" },

{

"describeUrl" : "/services/data/v35.0/analytics/reports/00OR0000000JdVOMA0/describe",

"id" : "00OR0000000JdVOMA0",

"instancesUrl" : "/services/data/v35.0/analytics/reports/00OR0000000JdVOMA0/instances",

"name" : "My Leads rpt",

"url" : "/services/data/v35.0/analytics/reports/00OR0000000JdVOMA0" }

SEE ALSO:

Report List

Decode the Fact Map

Depending on how you run a report, the fact map in the report results can contain values for only summary or both summary and detailed data. The fact map values are expressed as keys, which you can programmatically use to visualize the report data. Fact map keys provide an index into each section of a fact map, from which you can access summary and detailed data.

The pattern for the fact map keys varies by report format as shown in this table.

Fact map key pattern Report format

Tabular

Summary

Matrix

T!T

: The grand total of a report. Both record data values and the grand total are represented by this key.

<First level row grouping_second level row grouping_third level row

grouping>!T

: T refers to the row grand total.

<First level row grouping_second level row grouping>!<First level column grouping_second level column grouping>

.

55

Examples: Reports REST API Resources

Each item in a row or column grouping is numbered starting with

0

. Here are some examples of fact map keys:

Description Fact Map

Key

0!T

1!T

0_0!T

0_1!T

The first item in the first-level grouping.

The second item in the first-level grouping.

The first item in the first-level grouping and the first item in the second-level grouping.

The first item in the first-level grouping and the second item in the second-level grouping.

Decode the Fact Map

Let’s look at examples of how fact map keys represent data as it appears in a Salesforce tabular, summary, or matrix report.

Tabular Report Fact Map

Here’s an example of an opportunities report in tabular format. Since tabular reports don’t have groupings, all of the record level data and summaries are expressed by the

T!T

key, which refers to the grand total.

Summary Report Fact Map

This example shows how the values in a summary report are represented in the fact map.

56

Examples: Reports REST API Resources Decode the Fact Map

Fact Map Key

0!T

1_0!T

Description

Summary for the value of opportunities in the Prospecting stage.

Summary of the probabilities for the Manufacturing opportunities in the Needs Analysis stage.

Matrix Report Fact Map

Here’s an example of some fact map keys for data in a matrix opportunities report with a couple of row and column groupings.

Fact Map Key

0!0

0_0!0_0

2_1!1_1

T!T

Description

Total opportunity amount in the Prospecting stage in Q4 2010.

Total opportunity amount in the Prospecting stage in the Manufacturing sector in October 2010.

Total value of opportunities in the Value Proposition stage in the Technology sector in February 2011.

Grand total summary for the report.

SEE ALSO:

Execute Sync

Execute Async

57

Examples: Reports REST API Resources Get Report Data without Saving Changes to or Creating a

Report

Get Report Data without Saving Changes to or Creating a Report

Run a report without creating a report or changing an existing one by making a POST request to the query

resource. Get report data without filling up your org with unnecessary reports.

Example

Get report data using the query

resource.

/services/data/v37.0/analytics/reports/query

Include report criteria as reportMetadata

in the POST request body. This POST request gets data about Opportunities:

{

"reportMetadata" : {

"aggregates" : [ "RowCount" ],

"chart" : null,

"crossFilters" : [ ],

"currency" : null,

"description" : null,

"detailColumns" : [ "OPPORTUNITY_NAME", "TYPE", "LEAD_SOURCE", "AMOUNT", "CLOSE_DATE",

"NEXT_STEP", "STAGE_NAME", "PROBABILITY", "FISCAL_QUARTER", "AGE", "CREATED_DATE",

"FULL_NAME", "ROLLUP_DESCRIPTION", "ACCOUNT_NAME" ],

"developerName" : "OpportunityReport",

"division" : null,

"folderId" : "00DD000000086ujMAA",

"groupingsAcross" : [ ],

"groupingsDown" : [ ],

"hasDetailRows" : true,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OD0000001leVCMAY",

"name" : "Matrix",

"reportBooleanFilter" : null,

"reportFilters" : [ ],

"reportFormat" : "MATRIX",

"reportType" : {

"label" : "Opportunities",

"type" : "Opportunity"

},

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CLOSE_DATE",

"durationValue" : "CUSTOM",

"endDate" : null,

"startDate" : null

},

"standardFilters" : [ {

"name" : "open",

"value" : "all"

58

Examples: Reports REST API Resources Get Report Data without Saving Changes to or Creating a

Report

}

}

}, {

"name" : "probability",

"value" : ">0"

} ]

The response to the POST request returns report data, but doesn’t create or save a report.

{

"attributes" : {

"describeUrl" : "/services/data/v37.0/analytics/reports/null/describe",

"instancesUrl" : "/services/data/v37.0/analytics/reports/null/instances",

"reportId" : null,

},

"reportName" : "Matrix",

"type" : "Report"

"allData" : true,

"factMap" : {

"T!T" : {

"aggregates" : [ {

"label" : "9",

"value" : 9

} ],

"rows" : [ {

"dataCells" : [ {

"label" : "salesforce.com - 5000 Widgets",

"value" : "006D000000CzmqYIAR"

}, {

"label" : "New Business",

"value" : "New Business"

}, {

"label" : "Advertisement",

"value" : "Advertisement"

}, {

"label" : "$500,000.00",

"value" : {

}

}, {

"amount" : 500000,

"currency" : null

"label" : "9/19/2013",

"value" : "2013-09-19"

}, {

"label" : "Closed!",

"value" : "Closed!"

}, {

"label" : "Closed Won",

"value" : "Closed Won"

}, {

"label" : "100%",

"value" : 100

}, {

"label" : "Q2-2007",

"value" : "Q2-2007"

59

Examples: Reports REST API Resources

}, {

"label" : "0",

"value" : 0

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Global Media",

"value" : "001D000000KtTTqIAN"

} ]

}, {

"dataCells" : [ {

"label" : "salesforce.com - 500 Widgets",

"value" : "006D000000CzmqZIAR"

}, {

"label" : "Existing Business",

"value" : "Existing Business"

}, {

"label" : "Advertisement",

"value" : "Advertisement"

}, {

"label" : "$50,000.00",

"value" : {

"amount" : 50000,

"currency" : null

}

}, {

"label" : "9/19/2013",

"value" : "2013-09-19"

}, {

"label" : "Closed!",

"value" : "Closed!"

}, {

"label" : "Closed Won",

"value" : "Closed Won"

}, {

"label" : "100%",

"value" : 100

}, {

"label" : "Q2-2007",

"value" : "Q2-2007"

}, {

"label" : "0",

"value" : 0

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

Get Report Data without Saving Changes to or Creating a

Report

60

Examples: Reports REST API Resources

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Global Media",

"value" : "001D000000KtTTqIAN"

} ]

}, {

"dataCells" : [ {

"label" : "Acme - 1,200 Widgets",

"value" : "006D000000CzmqbIAB"

}, {

"label" : "Existing Business",

"value" : "Existing Business"

}, {

"label" : "Trade Show",

"value" : "Trade Show"

}, {

"label" : "$140,000.00",

"value" : {

"amount" : 140000,

"currency" : null

}

}, {

"label" : "10/22/2013",

"value" : "2013-10-22"

}, {

"label" : "Need estimate",

"value" : "Need estimate"

}, {

"label" : "Value Proposition",

"value" : "Value Proposition"

}, {

"label" : "50%",

"value" : 50

}, {

"label" : "Q2-2007",

"value" : "Q2-2007"

}, {

"label" : "134",

"value" : 134

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Acme",

61

Get Report Data without Saving Changes to or Creating a

Report

Examples: Reports REST API Resources

"value" : "001D000000KtTTrIAN"

} ]

}, {

"dataCells" : [ {

"label" : "salesforce.com - 1,000 Widgets",

"value" : "006D000000CzmqeIAB"

}, {

"label" : "New Business",

"value" : "New Business"

}, {

"label" : "Advertisement",

"value" : "Advertisement"

}, {

"label" : "$100,000.00",

"value" : {

}

}, {

"amount" : 100000,

"currency" : null

"label" : "10/22/2013",

"value" : "2013-10-22"

}, {

"label" : "Close the deal!",

"value" : "Close the deal!"

}, {

"label" : "Negotiation/Review",

"value" : "Negotiation/Review"

}, {

"label" : "90%",

"value" : 90

}, {

"label" : "Q2-2007",

"value" : "Q2-2007"

}, {

"label" : "134",

"value" : 134

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

} ]

}, {

"label" : "salesforce.com",

"value" : "001D000000KtTTsIAN"

"dataCells" : [ {

"label" : "Global Media - 400 Widgets",

"value" : "006D000000CzmqaIAB"

}, {

Get Report Data without Saving Changes to or Creating a

Report

62

Examples: Reports REST API Resources

"label" : "New Business",

"value" : "New Business"

}, {

"label" : "Partner",

"value" : "Partner"

}, {

"label" : "$40,000.00",

"value" : {

"amount" : 40000,

"currency" : null

}

}, {

"label" : "11/20/2013",

"value" : "2013-11-20"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Id. Decision Makers",

"value" : "Id. Decision Makers"

}, {

"label" : "60%",

"value" : 60

}, {

"label" : "Q3-2007",

"value" : "Q3-2007"

}, {

"label" : "134",

"value" : 134

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Global Media",

"value" : "001D000000KtTTqIAN"

} ]

}, {

"dataCells" : [ {

"label" : "Acme - 600 Widgets",

"value" : "006D000000CzmqcIAB"

}, {

"label" : "New Business",

"value" : "New Business"

}, {

"label" : "Trade Show",

"value" : "Trade Show"

}, {

"label" : "$70,000.00",

63

Get Report Data without Saving Changes to or Creating a

Report

Examples: Reports REST API Resources

"value" : {

"amount" : 70000,

"currency" : null

}

}, {

"label" : "12/18/2013",

"value" : "2013-12-18"

}, {

"label" : "Need estimate",

"value" : "Need estimate"

}, {

"label" : "Needs Analysis",

"value" : "Needs Analysis"

}, {

"label" : "20%",

"value" : 20

}, {

"label" : "Q3-2007",

"value" : "Q3-2007"

}, {

"label" : "134",

"value" : 134

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Acme",

"value" : "001D000000KtTTrIAN"

} ]

}, {

"dataCells" : [ {

"label" : "salesforce.com - 2,000 Widgets",

"value" : "006D000000CzmqfIAB"

}, {

"label" : "Existing Business",

"value" : "Existing Business"

}, {

"label" : "Partner",

"value" : "Partner"

}, {

"label" : "$20,000.00",

"value" : {

"amount" : 20000,

"currency" : null

}

}, {

"label" : "12/20/2013",

"value" : "2013-12-20"

Get Report Data without Saving Changes to or Creating a

Report

64

Examples: Reports REST API Resources

}, {

"label" : "Meet at Widget Conference",

"value" : "Meet at Widget Conference"

}, {

"label" : "Value Proposition",

"value" : "Value Proposition"

}, {

"label" : "50%",

"value" : 50

}, {

"label" : "Q3-2007",

"value" : "Q3-2007"

}, {

"label" : "134",

"value" : 134

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "salesforce.com",

"value" : "001D000000KtTTsIAN"

} ]

}, {

"dataCells" : [ {

"label" : "Acme - 200 Widgets",

"value" : "006D000000CzmqdIAB"

}, {

"label" : "Existing Business",

"value" : "Existing Business"

}, {

"label" : "Word of mouth",

"value" : "Word of mouth"

}, {

"label" : "$20,000.00",

"value" : {

"amount" : 20000,

"currency" : null

}

}, {

"label" : "2/20/2014",

"value" : "2014-02-20"

}, {

"label" : "Need estimate",

"value" : "Need estimate"

}, {

"label" : "Prospecting",

"value" : "Prospecting"

}, {

Get Report Data without Saving Changes to or Creating a

Report

65

Examples: Reports REST API Resources

"label" : "10%",

"value" : 10

}, {

"label" : "Q4-2007",

"value" : "Q4-2007"

}, {

"label" : "134",

"value" : 134

}, {

"label" : "1/4/2016",

"value" : "2016-01-04"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Acme",

"value" : "001D000000KtTTrIAN"

} ]

}, {

"dataCells" : [ {

"label" : "Fred",

"value" : "006D000000Czq0uIAB"

}, {

"label" : "-",

"value" : null

}, {

"label" : "-",

"value" : null

}, {

"label" : "-",

"value" : null

}, {

"label" : "2/26/2016",

"value" : "2016-02-26"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Id. Decision Makers",

"value" : "Id. Decision Makers"

}, {

"label" : "60%",

"value" : 60

}, {

"label" : "Q1-2016",

"value" : "Q1-2016"

}, {

"label" : "85",

"value" : 85

}, {

"label" : "2/22/2016",

66

Get Report Data without Saving Changes to or Creating a

Report

Examples: Reports REST API Resources

"value" : "2016-02-22"

}, {

"label" : "Fred Williamson",

"value" : "005D0000001bV42IAE"

}, {

"label" : "-",

"value" : null

}, {

"label" : "Fred",

"value" : "001D000000KtqzeIAB"

} ]

} ]

}

},

"groupingsAcross" : {

},

"groupings" : [ ]

"groupingsDown" : {

"groupings" : [ ]

},

"hasDetailRows" : true,

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"RowCount" : {

"dataType" : "int",

"label" : "Record Count"

},

}

"detailColumnInfo" : {

"OPPORTUNITY_NAME" : {

"dataType" : "string",

},

"label" : "Opportunity Name"

"TYPE" : {

"dataType" : "picklist",

},

"label" : "Type"

"LEAD_SOURCE" : {

"dataType" : "picklist",

},

"label" : "Lead Source"

"AMOUNT" : {

"dataType" : "currency",

"label" : "Amount"

},

"CLOSE_DATE" : {

"dataType" : "date",

"label" : "Close Date"

},

"NEXT_STEP" : {

"dataType" : "string",

},

"label" : "Next Step"

"STAGE_NAME" : {

67

Get Report Data without Saving Changes to or Creating a

Report

Examples: Reports REST API Resources Get Report Data without Saving Changes to or Creating a

Report

"dataType" : "picklist",

"label" : "Stage"

},

"PROBABILITY" : {

"dataType" : "percent",

"label" : "Probability (%)"

},

"FISCAL_QUARTER" : {

},

"dataType" : "string",

"label" : "Fiscal Period"

"AGE" : {

"dataType" : "int",

},

"label" : "Age"

"CREATED_DATE" : {

"dataType" : "datetime",

},

"label" : "Created Date"

"FULL_NAME" : {

"dataType" : "string",

"label" : "Opportunity Owner"

},

"ROLLUP_DESCRIPTION" : {

"dataType" : "string",

"label" : "Owner Role"

},

"ACCOUNT_NAME" : {

"dataType" : "string",

"label" : "Account Name"

}

},

"groupingColumnInfo" : { }

},

"reportMetadata" : {

"aggregates" : [ "RowCount" ],

"chart" : null,

"crossFilters" : [ ],

"currency" : null,

"description" : null,

"detailColumns" : [ "OPPORTUNITY_NAME", "TYPE", "LEAD_SOURCE", "AMOUNT", "CLOSE_DATE",

"NEXT_STEP", "STAGE_NAME", "PROBABILITY", "FISCAL_QUARTER", "AGE", "CREATED_DATE",

"FULL_NAME", "ROLLUP_DESCRIPTION", "ACCOUNT_NAME" ],

"developerName" : null,

"division" : null,

"folderId" : "00DD000000086ujMAA",

"groupingsAcross" : [ ],

"groupingsDown" : [ ],

"hasDetailRows" : true,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : null,

"name" : "Matrix",

"reportBooleanFilter" : null,

68

Examples: Reports REST API Resources Save Changes to Reports

}

}

"reportFilters" : [ ],

"reportFormat" : "TABULAR",

"reportType" : {

"label" : "Opportunities",

},

"type" : "Opportunity"

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CLOSE_DATE",

"durationValue" : "CUSTOM",

"endDate" : null,

"startDate" : null

},

"standardFilters" : [ {

"name" : "open",

"value" : "all"

}, {

"name" : "probability",

"value" : ">0"

} ]

Save Changes to Reports

Save changes to a report by sending a PATCH request to the Report resource.

Note: Saving a report deletes any running async report jobs because they will be obsolete.

Example

For report 00OD0000001cxIE, you want to change the report name to “myUpdatedReport” and change the folder that contains the report. You save the changes to the report.

This PATCH request

/services/data/v34.0/analytics/reports/00OD0000001cxIE

to the Report resource updates and saves the report.

{

"reportMetadata" : {

"name":"myUpdatedReport",

"folderId":"00DD00000007enH"}

}

The response to the PATCH request returns the following details about the updated, saved report.

{

"reportExtendedMetadata" : {

...

},

"reportMetadata" : {

69

Examples: Reports REST API Resources

}

"aggregates" : [ "RowCount" ],

"chart" : null,

"currency" : null,

"description" : null,

"detailColumns" : [

"USERS.NAME",

"ACCOUNT.NAME",

"TYPE",

"DUE_DATE",

"LAST_UPDATE",

"ADDRESS1_STATE" ],

"developerName" : "myreport",

"division" : null,

"folderId" : "00DD00000007enHMAQ",

"groupingsAcross" : [ ],

"groupingsDown" : [ ],

"hasDetailRows" : true,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OD0000001cxIEMAY",

"name" : "myUpdatedReport",

"reportBooleanFilter" : null,

"reportFilters" : [ ],

"reportFormat" : "TABULAR",

"reportType" : {

"label" : "Accounts",

"type" : "AccountList" },

"scope" : "user",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CREATED_DATE",

"durationValue" : "CUSTOM",

"endDate" : null,

"startDate" : null },

"standardFilters" : null },

"reportTypeMetadata" : {

...

}

Clone Reports

Creates a copy of a custom, standard, or public report by sending a POST request to the Report List resource.

Example

You want to clone report 00OD0000001cxIE and name the cloned report as "myNewReport."

Clone Reports

70

Examples: Reports REST API Resources Clone Reports

This POST request

/services/data/v34.0/analytics/reports?cloneId=00OD0000001cxIE

to the Report List resource clones the report.

{ "reportMetadata" :

{"name":"myNewReport"}

}

The response to the POST request returns the following details about the cloned report.

{

"reportExtendedMetadata" : {

...

},

"reportMetadata" : {

"aggregates" : [ "RowCount" ],

"chart" : null,

"currency" : null,

"description" : null,

"detailColumns" : [

"USERS.NAME",

"ACCOUNT.NAME",

"TYPE",

"DUE_DATE",

"LAST_UPDATE",

"ADDRESS1_STATE" ],

"developerName" : "myreport2",

"division" : null,

"folderId" : "005D0000001UlszIAC",

"groupingsAcross" : [ ],

"groupingsDown" : [ ],

"hasDetailRows" : true,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OD0000001jabSMAQ",

"name" : "myNewReport",

"reportBooleanFilter" : null,

"reportFilters" : [ ],

"reportFormat" : "TABULAR",

"reportType" : {

"label" : "Accounts",

"type" : "AccountList" },

"scope" : "user",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CREATED_DATE",

"durationValue" : "CUSTOM",

"endDate" : null,

"reportTypeMetadata" : {

...

}

"startDate" : null },

"standardFilters" : null },

}

71

Examples: Reports REST API Resources Delete Reports

Delete Reports

Delete a report by sending a DELETE request to the Report resource. Deleted reports are moved to the Recycle Bin.

Note: Deleting a report also cancels any running async report jobs and deletes all scheduled notifications.

Example

This DELETE request

/services/data/v34.0/analytics/reports/00OD0000001cxIE

to the Report resource deletes the report and returns a 204 HTTP response code with no content in the response body.

72

CHAPTER 3

Examples: Dashboards REST API Resources

In this chapter ...

•

Get List of Recently

Used Dashboards

•

Get Dashboard

Results

•

Filter Dashboard

Results

•

Get Dashboard

Status

•

Refresh a Dashboard

•

Save a Dashboard

•

Set a Sticky

Dashboard Filter

•

Return Details About

Dashboard

Components

•

Get Dashboard

Metadata

•

Clone a Dashboard

•

Delete a Dashboard

The Dashboards API is designed to let you access and refresh dashboards easily. Use the API to:

•

Get List of Recently Used Dashboards

Get a list of dashboards with URLs to access status and results.

•

Get Dashboard Results

Get dashboard metadata, data, and status.

•

Filter Dashboard Results

Filter dashboard results, status, or refresh requests.

•

Get Dashboard Status

Get dashboard refresh status.

•

Refresh a Dashboard

Trigger a dashboard refresh.

•

Save a Dashboard

Save changes to a dashboard.

•

Clone a Dashboard

Make a copy of an existing dashboard.

•

Delete a Dashboard

Clean up unused and obsolete dashboards.

73

Examples: Dashboards REST API Resources Get List of Recently Used Dashboards

Get List of Recently Used Dashboards

You can get a list of recently used dashboards by using the Dashboard resource.

Use a GET request on the

Dashboard List resource to retrieve a list of recently used dashboards. The list is sorted by the date when the

dashboard was last refreshed.

Example Usage

/services/data/v35.0/analytics/dashboards

Example Response Body

In this case, the Dashboard resource returns information for two dashboards. Each URL handle stores the status or results for the dashboard.

[ {

"id" : "01ZD00000007QeuMAE",

"name" : "Adoption Dashboard",

"statusUrl" : "/services/data/v35.0/analytics/dashboards/01ZD00000007QeuMAE/status",

"url" : "/services/data/v35.0/analytics/dashboards/01ZD00000007QeuMAE"

}, {

"id" : "01ZD00000007QevMAE",

"name" : "Global Sales Dashboard",

"statusUrl" : "/services/data/v35.0/analytics/dashboards/01ZD00000007QevMAE/status",

"url" : "/services/data/v35.0/analytics/dashboards/01ZD00000007QevMAE"

} ]

SEE ALSO:

Dashboard List

Get Dashboard Results

You can get dashboard metadata, data, and status by sending a GET request to the Dashboard Results resource.

Use a GET request to the

Dashboard Results resource to retrieve metadata, data, and status for a dashboard and its components. The

results response contains:

•

Metadata: information about the dashboard as a whole, including the dashboard ID, name, component metadata, and any dashboard filters.

•

Data: underlying report data for each component, filtered by the optional filter parameters. For more information about filtering,

see Filter Dashboard Results

.

•

Status: data and refresh status for each component of the dashboard. The data status can be

NODATA

,

DATA

, or

ERROR

. If an error occurs, the component status will contain additional properties with the error code, message, and severity. The refresh status can be

IDLE

, if components are finished running, or

RUNNING

, if components are still being refreshed.

Example Usage

/services/data/v31.0/analytics/dashboards/01ZD00000007S89MAE

Example Response Body

{

"componentData" : [ {

74

Examples: Dashboards REST API Resources

"componentId" : "01aD0000000a36LIAQ",

"reportResult" : {

"attributes" : null,

"allData" : true,

"factMap" : {

"T!T" : {

"aggregates" : [ {

"label" : "USD 67,043,365.50",

"value" : 67043365.50166918337345123291015625

} ]

},

"0!T" : {

"aggregates" : [ {

},

} ]

"label" : "USD 10,083.33",

"value" : 10083.333333333333939663134515285491943359375

"1!T" : {

"aggregates" : [ {

"label" : "USD 25,016,768.67",

"value" : 25016768.670066006481647491455078125

} ]

},

"2!T" : {

"aggregates" : [ {

"label" : "USD 42,016,513.50",

"value" : 42016513.49826984107494354248046875

} ]

},

}

"groupingsAcross" : null,

"groupingsDown" : {

"groupings" : [ {

"groupings" : [ ],

"key" : "0",

"label" : "-",

"value" : null

}, {

"groupings" : [ ],

"key" : "1",

"label" : "Existing Business",

"value" : "Existing Business"

}, {

"groupings" : [ ],

"key" : "2",

"label" : "New Business",

"value" : "New Business"

} ]

},

"hasDetailRows" : false,

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"s!AMOUNT" : {

"acrossGroupingContext" : null,

75

Get Dashboard Results

Examples: Dashboards REST API Resources Get Dashboard Results

"dataType" : "currency",

"downGroupingContext" : null,

"label" : "Sum of Amount"

}

},

"detailColumnInfo" : { },

"groupingColumnInfo" : {

"TYPE" : {

"dataType" : "picklist",

"groupingLevel" : 0,

"label" : "Type"

}

}

},

"reportMetadata" : {

"aggregates" : [ "s!AMOUNT" ],

"chart" : null,

"currency" : "USD",

"description" : null,

"detailColumns" : [ ],

"developerName" : "Simple_Test",

"division" : null,

"folderId" : "00lR0000000M8IiIAK",

"groupingsAcross" : [ ],

"groupingsDown" : [ {

"dateGranularity" : "None",

"name" : "TYPE",

"sortAggregate" : null,

"sortOrder" : "Asc"

} ],

"hasDetailRows" : false,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OD0000001g2nWMAQ",

"name" : "Simple Test",

"reportBooleanFilter" : null,

"reportFilters" : [ ],

"reportFormat" : "SUMMARY",

"reportType" : {

"label" : "Opportunities",

"type" : "Opportunity"

},

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : { "column" : "CLOSE_DATE", "durationValue" : "CUSTOM",

"endDate" : null, "startDate" : null },

"standardFilters" : [

{ "name" : "open", "value" : "all" },

{ "name" : "probability", "value" : ">0" } ]

},

}

"status" : {

76

Examples: Dashboards REST API Resources Get Dashboard Results

"dataStatus" : "DATA",

"errorCode" : null,

"errorMessage" : null,

"errorSeverity" : null,

}

} ],

"refreshDate" : "2014-04-09T00:28:16.000+0000",

"refreshStatus" : "IDLE"

"dashboardMetadata" : {

"attributes" : {

"dashboardId" : "01ZD00000007S89MAE",

"dashboardName" : "Simple Dashboard",

"statusUrl" : "/services/data/v31.0/analytics/dashboards/01ZD00000007S89MAE/status",

"type" : "Dashboard"

},

"canChangeRunningUser" : false,

"components" : [ {

"componentData" : 0,

"footer" : null,

"header" : null,

"id" : "01aD0000000a36LIAQ",

"properties" : {

"aggregates" : [ { "name" : "s!AMOUNT" } ],

"autoSelectColumns" : false,

"groupings" : null,

"maxRows" : null,

"sort" : { "column" : "TYPE", "sortOrder" : "asc" },

"useReportChart" : false,

"visualizationProperties" : {

"breakPoints" : [ {

"aggregateName" : "s!AMOUNT",

"breaks" : [

{ "color" : "000000", "lowerBound" : null, "upperBound" : -1 },

{ "color" : "000000", "lowerBound" : -1, "upperBound" : 0 },

{ "color" : "000000", "lowerBound" : 0, "upperBound" : null } ]

} ],

"metricLabel" : null },

"visualizationType" : "Metric" },

"reportId" : "00OD0000001g2nWMAQ",

"title" : null,

"type" : "Report"

} ],

"description" : null,

"developerName" : "Simple_Dashboard",

"filters" : [ {

"name" : "Amount",

"options" : [ {

"alias" : null,

"endValue" : null,

"id" : "0ICD00000004CBiOAM",

"operation" : "greaterThan",

"startValue" : null,

77

Examples: Dashboards REST API Resources Filter Dashboard Results

}

}

"value" : "USD 2000000"

} ],

"selectedOption" : null

} ],

"folderId" : "00lR0000000DrojIAC",

"id" : "01ZD00000007S89MAE",

"layout" : {

"columns" : [ {

},

"components" : [ 0 ]

} ]

"name" : "Simple Dashboard",

"runningUser" : {

"displayName" : "Allison Wheeler",

"id" : "005D00000016V2qIAE"

}

SEE ALSO:

Dashboard Results

Filter Dashboard Results

You can filter dashboard results, status, or refresh requests, by using filter parameters.

Dashboard results are always unfiltered, unless you have specified filter parameters in your request. When requesting a dashboard result, status, or refresh, you can specify up to three optional filter parameters: filter1

, filter2

and filter3

. These parameters allow you to apply filter options, which can be selected from the filters that are currently defined for the dashboard. Filters can be applied to the following requests:

•

A GET request on the

Dashboard Results resource: returns data filtered by the specified parameters.

•

A PUT request on the

Dashboard Results

resource: refreshes the data that has been filtered by the specified parameters.

•

A GET request on the

Dashboard Status

resource: returns status for the data that has been filtered by the specified parameters.

Example Usage

A dashboard with one filter ("Country") and two options ("United States" and "Canada") appears like this in the dashboard metadata:

{

"dashboardMetadata" : {

...

"filters" : [ {

"name" : "Country",

"options" : [ {

"id" : "0ICxx0000000001GAA",

"alias" : "United States",

"operation" : "equals",

"value" : "US",

"startValue" : null,

"endValue" : null

} ], [ {

78

Examples: Dashboards REST API Resources Get Dashboard Status

"id" : "0ICxx0000000002GAA",

"alias" : "Canada",

"operation" : "equals",

"value" : "CA",

"startValue" : null,

"endValue" : null

} ],

...

}

To retrieve dashboard results with a filter of "Country equals Canada" you could make the following GET request:

/services/data/v31.0/analytics/dashboards/01Zxx0000000000000?filter1=0ICxx0000000002GAA

SEE ALSO:

Dashboard Results

Dashboard Status

Get Dashboard Status

You can get the dashboard status by sending a GET request to the Dashboard Status resource.

Use the Dashboard Status

resource to retrieve a status for each component of the dashboard. The components are listed in the order in which they were refreshed. The request returns

IDLE

if a component is not currently being refreshed, and

RUNNING

if a component is currently being refreshed.

Example Usage

To retrieve the status for a dashboard with an ID of

01ZD00000007QevMAE

, you could make the following request:

/services/data/v31.0/analytics/dashboards/01ZD00000007QevMAE/status

Example Response Body

The response contains the status for each component, along with the refresh date and time:

{

"componentStatus" : [ {

"componentId" : "01aD0000000J7M7",

"refreshDate" : "2014-03-10T17:26:07.000+0000",

"refreshStatus" : "IDLE"

}, {

"componentId" : "01aD0000000J7M9",

"refreshDate" : "2014-03-10T17:26:08.000+0000",

"refreshStatus" : "IDLE"

}, {

"componentId" : "01aD0000000J7MB",

"refreshDate" : "2014-03-10T17:26:09.000+0000",

"refreshStatus" : "IDLE"

79

Examples: Dashboards REST API Resources Refresh a Dashboard

}

} ]

SEE ALSO:

Dashboard Status

Refresh a Dashboard

You can refresh a dashboard by using a PUT Dashboard Results request.

Use a PUT request on the Dashboard Results

resource to trigger a refresh of a dashboard. The refresh response returns the URL of the status resource after the refresh is triggered. If filter parameters are included in the PUT request, only the filtered data will be refreshed.

For more information on filtering, see

Filter Dashboard Results

.

Example Usage

The following PUT request refreshes the dashboard with the ID of

01ZD00000007S89MAE

.

/services/data/v31.0/analytics/dashboards/01ZD00000007S89MAE

Example Request Body

None required.

Example Response Body

The response contains the status URL for the refreshed dashboard:

{

"statusUrl" : "/services/data/v31.0/analytics/dashboards/01ZD00000007S89MAE/status"

}

SEE ALSO:

Dashboard Results

Save a Dashboard

You can save changes to a dashboard by sending a PATCH request to the Dashboard Results resource.

Use a PATCH request on the Dashboard Results resource to save changes to a dashboard.

Example Usage

/services/data/v31.0/analytics/dashboards/01ZD00000007S89MAE

Example Request Body

{

"dashboardMetadata" : {

"name" : "Sales Dashboard",

}

}

80

Examples: Dashboards REST API Resources

Example Response Body

{

"componentData" : [ {

"componentId" : "01aD0000000a36LIAQ",

"reportResult" : {

"attributes" : null,

"allData" : true,

"factMap" : {

"T!T" : {

"aggregates" : [ {

"label" : "USD 67,043,365.50",

"value" : 67043365.50166918337345123291015625

} ]

},

"0!T" : {

"aggregates" : [ {

},

} ]

"label" : "USD 10,083.33",

"value" : 10083.333333333333939663134515285491943359375

"1!T" : {

"aggregates" : [ {

"label" : "USD 25,016,768.67",

"value" : 25016768.670066006481647491455078125

} ]

},

"2!T" : {

"aggregates" : [ {

"label" : "USD 42,016,513.50",

"value" : 42016513.49826984107494354248046875

} ]

}

},

"groupingsAcross" : null,

"groupingsDown" : {

"groupings" : [ {

"groupings" : [ ],

"key" : "0",

"label" : "-",

"value" : null

}, {

"groupings" : [ ],

"key" : "1",

"label" : "Existing Business",

"value" : "Existing Business"

}, {

"groupings" : [ ],

"key" : "2",

"label" : "New Business",

"value" : "New Business"

} ]

},

"hasDetailRows" : false,

81

Save a Dashboard

Examples: Dashboards REST API Resources Save a Dashboard

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"s!AMOUNT" : {

"acrossGroupingContext" : null,

"dataType" : "currency",

"downGroupingContext" : null,

"label" : "Sum of Amount"

}

},

"detailColumnInfo" : { },

"groupingColumnInfo" : {

"TYPE" : {

"dataType" : "picklist",

"groupingLevel" : 0,

"label" : "Type"

}

}

},

"reportMetadata" : {

"aggregates" : [ "s!AMOUNT" ],

"chart" : null,

"currency" : "USD",

"description" : null,

"detailColumns" : [ ],

"developerName" : "Simple_Test",

"division" : null,

"folderId" : "00lR0000000M8IiIAK",

"groupingsAcross" : [ ],

"groupingsDown" : [ {

"dateGranularity" : "None",

"name" : "TYPE",

"sortAggregate" : null,

"sortOrder" : "Asc"

} ],

"hasDetailRows" : false,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OD0000001g2nWMAQ",

"name" : "Simple Test",

"reportBooleanFilter" : null,

"reportFilters" : [ ],

"reportFormat" : "SUMMARY",

"reportType" : {

"label" : "Opportunities",

},

"type" : "Opportunity"

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : { "column" : "CLOSE_DATE", "durationValue" : "CUSTOM",

"endDate" : null, "startDate" : null },

"standardFilters" : [

{ "name" : "open", "value" : "all" },

82

Examples: Dashboards REST API Resources Save a Dashboard

{ "name" : "probability", "value" : ">0" } ]

}

},

"status" : {

"dataStatus" : "DATA",

"errorCode" : null,

"errorMessage" : null,

"errorSeverity" : null,

"refreshDate" : "2014-04-09T00:28:16.000+0000",

"refreshStatus" : "IDLE"

}

} ],

"dashboardMetadata" : {

"attributes" : {

"dashboardId" : "01ZD00000007S89MAE",

"dashboardName" : "Service Dept Dashboard",

"statusUrl" : "/services/data/v31.0/analytics/dashboards/01ZD00000007S89MAE/status",

"type" : "Dashboard"

},

"canChangeRunningUser" : false,

"components" : [ {

"componentData" : 0,

"footer" : null,

"header" : null,

"id" : "01aD0000000a36LIAQ",

"properties" : {

"aggregates" : [ { "name" : "s!AMOUNT" } ],

"autoSelectColumns" : false,

"groupings" : null,

"maxRows" : null,

"sort" : { "column" : "TYPE", "sortOrder" : "asc" },

"useReportChart" : false,

"visualizationProperties" : {

"breakPoints" : [ {

"aggregateName" : "s!AMOUNT",

"breaks" : [

{ "color" : "000000", "lowerBound" : null, "upperBound" : -1 },

{ "color" : "000000", "lowerBound" : -1, "upperBound" : 0 },

{ "color" : "000000", "lowerBound" : 0, "upperBound" : null } ]

} ],

"metricLabel" : null },

"visualizationType" : "Metric" },

"reportId" : "00OD0000001g2nWMAQ",

"title" : null,

"type" : "Report"

} ],

"description" : null,

"developerName" : "Simple_Dashboard",

"filters" : [ {

"name" : "Amount",

"options" : [ {

"alias" : null,

83

Examples: Dashboards REST API Resources Set a Sticky Dashboard Filter

}

}

"endValue" : null,

"id" : "0ICD00000004CBiOAM",

"operation" : "greaterThan",

"startValue" : null,

"value" : "USD 2000000"

} ],

"selectedOption" : null

} ],

"folderId" : "00lR0000000DrojIAC",

"id" : "01ZD00000007S89MAE",

"layout" : {

"columns" : [ {

"components" : [ 0 ]

},

} ]

"name" : "Simple Dashboard",

"runningUser" : {

"displayName" : "Allison Wheeler",

"id" : "005D00000016V2qIAE"

}

Set a Sticky Dashboard Filter

Set a default filter value which gets applied to a dashboard when you open it. The default filter value you specify only applies to you

(other people won’t see it when they open the dashboard). If you change the filter value while viewing the dashboard, then the filter value you set in the user interface overwrites the value you set via the API. To set sticky filters for a dashboard, canUseStickyFilter must equal true

.

Use a PATCH request on the

Dashboard Results

resource and append the parameter isStickyFilterSave=true

to set a sticky filter.

In the request body, set the selectedOption

property to the index of the filter option you’d like to apply.

Example Usage

/services/data/v40.0/analytics/dashboards/0IBR00000004D4iOAE?isStickyFilterSave=true

Example Request Body

{

"filters" : [ {

"errorMessage" : null,

"id" : "0IBR00000004D4iOAE",

"name" : "Billing City",

"options" : [ {

"alias" : "New York City",

"endValue" : null,

"id" : "0ICR00000004FtQOAU",

"operation" : "equals",

"startValue" : null,

"value" : "New York City"

}, {

84

Examples: Dashboards REST API Resources Return Details About Dashboard Components

}

]

"alias" : "Chicago",

"endValue" : null,

"id" : "0ICR00000004FtROAU",

"operation" : "equals",

"startValue" : null,

"value" : "Chicago"

}, {

"alias" : "Los Angeles",

"endValue" : null,

"id" : "0ICR00000004FtSOAU",

"operation" : "equals",

],

}

"startValue" : null,

"value" : "Los Angeles"

"selectedOption" : 1

}

Example Response Body

If successful, an empty response body is returned.

Return Details About Dashboard Components

Get details about one or more dashboard components using a POST request.

Use a POST request on the Dashboard Results resource to get details about one or more dashboard components. Specify which dashboard

components you want details about using componentIds

in the request body. Available in API versions 36.0 and later.

Example Usage

/services/data/v36.0/analytics/dashboards/01ZR00000008h2EMAQ

Example Request Body

{

"componentIds": ["01aR00000005aT4IAI", "01aR00000005aT5IAI"]

}

Example Response Body

{

"attributes" : {

"dashboardId" : "01ZR00000008h2EMAQ",

"dashboardName" : "Liz's Sales Manager Dashboard",

"describeUrl" :

"/services/data/v37.0/analytics/dashboards/01ZR00000008h2EMAQ/describe",

"statusUrl" : "/services/data/v37.0/analytics/dashboards/01ZR00000008h2EMAQ/status",

"type" : "Dashboard"

},

"componentData" : [ {

"componentId" : "01aR00000005aT4IAI",

"reportResult" : {

85

Examples: Dashboards REST API Resources

"attributes" : null,

"allData" : true,

"factMap" : {

"0!T" : {

"aggregates" : [ {

"label" : "$10,000.00",

"value" : 10000

} ]

},

"1!T" : {

"aggregates" : [ {

},

} ]

"label" : "$110,000.00",

"value" : 110000

"0_0!T" : {

"aggregates" : [ {

"label" : "$10,000.00",

"value" : 10000

} ]

},

"2_2!T" : {

"aggregates" : [ {

"label" : "$143.00",

"value" : 143

} ]

},

"2!T" : {

"aggregates" : [ {

"label" : "$400,398.00",

"value" : 400398

} ]

},

"0_1!T" : {

"aggregates" : [ {

},

} ]

"label" : "$0.00",

"value" : 0

"2_3!T" : {

"aggregates" : [ {

"label" : "$100,017.00",

"value" : 100017

} ]

},

"T!T" : {

"aggregates" : [ {

"label" : "$520,398.00",

"value" : 520398

} ]

},

"2_0!T" : {

"aggregates" : [ {

"label" : "$138.00",

86

Return Details About Dashboard Components

Examples: Dashboards REST API Resources

"value" : 138

} ]

},

"1_0!T" : {

"aggregates" : [ {

"label" : "$110,000.00",

"value" : 110000

} ]

},

"2_1!T" : {

"aggregates" : [ {

"label" : "$300,100.00",

"value" : 300100

} ]

}

},

"groupingsAcross" : null,

"groupingsDown" : {

"groupings" : [ {

"groupings" : [ {

"groupings" : [ ],

"key" : "0_0",

"label" : "-",

"value" : null

}, {

"groupings" : [ ],

"key" : "0_1",

"label" : "-",

"value" : null

} ],

"key" : "0",

"label" : "January 2016",

"value" : "January 2016"

}, {

"groupings" : [ {

"groupings" : [ ],

"key" : "1_0",

"label" : "-",

"value" : null

} ],

"key" : "1",

"label" : "February 2016",

"value" : "February 2016"

}, {

"groupings" : [ {

"groupings" : [ ],

"key" : "2_0",

"label" : "-",

"value" : null

}, {

"groupings" : [ ],

"key" : "2_1",

"label" : "-",

"value" : null

87

Return Details About Dashboard Components

Examples: Dashboards REST API Resources Return Details About Dashboard Components

}, {

"groupings" : [ ],

"key" : "2_2",

"label" : "-",

"value" : null

}, {

"groupings" : [ ],

"key" : "2_3",

"label" : "-",

"value" : null

} ],

"key" : "2",

"label" : "March 2016",

"value" : "March 2016"

} ]

},

"hasDetailRows" : false,

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"s!AMOUNT" : {

"dataType" : "currency",

"label" : "Sum of Amount"

},

}

"detailColumnInfo" : { },

"groupingColumnInfo" : {

"ACCOUNT_NAME" : {

"dataType" : "string",

},

"groupingLevel" : 0,

"label" : "Account Name"

"CLOSE_DATE" : {

"dataType" : "date",

"groupingLevel" : 0,

"label" : "Close Date"

}

}

},

"reportMetadata" : {

"aggregates" : [ "s!AMOUNT" ],

"buckets" : [ {

"bucketType" : "picklist",

"devloperName" : "BucketField_47575792",

"label" : "Industry",

"nullTreatedAsZero" : false,

"otherBucketLabel" : null,

"sourceColumnName" : "INDUSTRY",

"values" : [ {

"label" : "Technology",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Agriculture", "Apparel", "Banking",

"Biotechnology", "Chemicals", "Communications", "Construction", "Consulting", "Education",

"Electronics" ]

}, {

88

Examples: Dashboards REST API Resources Return Details About Dashboard Components

"label" : "Energy",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Energy", "Engineering", "Entertainment",

"Environmental", "Finance", "Food & Beverage", "Government", "Healthcare", "Hospitality",

"Insurance", "Machinery", "Manufacturing" ]

}, {

"label" : "Healthcare",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Media", "Not For Profit", "Other", "Recreation",

"Retail", "Shipping", "Technology", "Telecommunications", "Transportation", "Utilities"

]

} ]

}, {

"bucketType" : "picklist",

"devloperName" : "BucketField_36625466",

"label" : "Stage",

"nullTreatedAsZero" : false,

"otherBucketLabel" : null,

"sourceColumnName" : "STAGE_NAME",

"values" : [ {

"label" : "Early",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Prospecting", "Qualification", "Needs Analysis"

]

}, {

"label" : "Late",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Value Proposition", "Id. Decision Makers",

"Perception Analysis", "Proposal/Price Quote", "Negotiation/Review" ]

}, {

"label" : "Won",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Closed Won" ]

}, {

"label" : "Lost",

} ]

} ],

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Closed Lost" ]

"chart" : null,

"crossFilters" : [ ],

"currency" : null,

"description" : null,

"detailColumns" : [ ],

"developerName" : "Deals_Closing_This_Quarter",

"division" : null,

"folderId" : "00lR0000000M8IiIAK",

"groupingsAcross" : [ ],

"groupingsDown" : [ {

"dateGranularity" : "None",

"name" : "ACCOUNT_NAME",

"sortAggregate" : null,

"sortOrder" : "Asc"

}, {

89

Examples: Dashboards REST API Resources

"dateGranularity" : "Month",

"name" : "CLOSE_DATE",

"sortAggregate" : null,

"sortOrder" : "Asc"

} ],

"hasDetailRows" : false,

"hasRecordCount" : true,

"historicalSnapshotDates" : [ ],

"id" : "00OR0000000K2UeMAK",

"name" : "Deals Closing This Quarter",

"reportBooleanFilter" : null,

"reportFilters" : [ {

"column" : "BucketField_36625466",

"isRunPageEditable" : true,

"operator" : "equals",

"value" : "Early,Late"

}, {

"column" : "TYPE",

"isRunPageEditable" : true,

"operator" : "equals",

"value" : "Existing Business,New Business"

} ],

"reportFormat" : "SUMMARY",

"reportType" : {

"label" : "Opportunities",

"type" : "Opportunity"

},

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CLOSE_DATE",

"durationValue" : "THIS_FISCAL_QUARTER",

"endDate" : "2016-06-30",

},

"startDate" : "2016-04-01"

"standardFilters" : [ {

"name" : "open",

"value" : "all"

}, {

"name" : "probability",

"value" : ">0"

} ]

},

}

"status" : {

"dataStatus" : "DATA",

"errorCode" : null,

"errorMessage" : null,

"errorSeverity" : null,

"refreshDate" : "2016-03-22T18:24:39.000+0000",

"refreshStatus" : "IDLE"

}

Return Details About Dashboard Components

90

Examples: Dashboards REST API Resources

}, {

"componentId" : "01aR00000005aT5IAI",

"reportResult" : {

"attributes" : null,

"allData" : true,

"factMap" : {

"0!T" : {

"aggregates" : [ {

"label" : "$634,493.00",

"value" : 634493

} ]

},

"1!T" : {

"aggregates" : [ {

"label" : "$590,036.00",

"value" : 590036

} ]

},

"0_0!T" : {

"aggregates" : [ {

},

} ]

"label" : "$14.00",

"value" : 14

"2!T" : {

"aggregates" : [ {

"label" : "$1,330,035.00",

"value" : 1330035

},

} ]

"0_1!T" : {

"aggregates" : [ {

"label" : "$36,021.00",

"value" : 36021

} ]

},

"0_2!T" : {

"aggregates" : [ {

"label" : "$5,000.00",

"value" : 5000

} ]

},

"1_3!T" : {

"aggregates" : [ {

},

} ]

"label" : "$500,000.00",

"value" : 500000

"T!T" : {

"aggregates" : [ {

"label" : "$2,554,564.00",

"value" : 2554564

} ]

},

91

Return Details About Dashboard Components

Examples: Dashboards REST API Resources

"0_3!T" : {

"aggregates" : [ {

"label" : "$440,000.00",

"value" : 440000

},

} ]

"1_4!T" : {

"aggregates" : [ {

"label" : "$13.00",

"value" : 13

} ]

},

"0_4!T" : {

"aggregates" : [ {

"label" : "$20,000.00",

"value" : 20000

} ]

},

"1_1!T" : {

"aggregates" : [ {

},

} ]

"label" : "$11.00",

"value" : 11

"0_5!T" : {

"aggregates" : [ {

"label" : "$90,000.00",

"value" : 90000

},

} ]

"1_2!T" : {

"aggregates" : [ {

"label" : "$40,000.00",

"value" : 40000

} ]

},

"0_6!T" : {

"aggregates" : [ {

"label" : "$43,320.00",

"value" : 43320

} ]

},

"0_7!T" : {

"aggregates" : [ {

},

} ]

"label" : "$138.00",

"value" : 138

"1_0!T" : {

"aggregates" : [ {

"label" : "$50,012.00",

"value" : 50012

} ]

},

92

Return Details About Dashboard Components

Examples: Dashboards REST API Resources

"2_2!T" : {

"aggregates" : [ {

"label" : "$100,017.00",

"value" : 100017

},

} ]

"2_3!T" : {

"aggregates" : [ {

"label" : "$20,018.00",

"value" : 20018

} ]

},

"2_4!T" : {

"aggregates" : [ {

"label" : "$0.00",

"value" : 0

} ]

},

"2_0!T" : {

"aggregates" : [ {

},

} ]

"label" : "$100,000.00",

"value" : 100000

},

}

"2_1!T" : {

"aggregates" : [ {

"label" : "$1,110,000.00",

"value" : 1110000

} ]

"groupingsAcross" : null,

"groupingsDown" : {

"groupings" : [ {

"groupings" : [ {

"groupings" : [ ],

"key" : "0_0",

"label" : "March 2013",

"value" : "2013-03-01"

}, {

"groupings" : [ ],

"key" : "0_1",

"label" : "July 2015",

"value" : "2015-07-01"

}, {

"groupings" : [ ],

"key" : "0_2",

"label" : "August 2015",

"value" : "2015-08-01"

}, {

"groupings" : [ ],

"key" : "0_3",

"label" : "September 2015",

"value" : "2015-09-01"

93

Return Details About Dashboard Components

Examples: Dashboards REST API Resources

}, {

"groupings" : [ ],

"key" : "0_4",

"label" : "October 2015",

"value" : "2015-10-01"

}, {

"groupings" : [ ],

"key" : "0_5",

"label" : "November 2015",

"value" : "2015-11-01"

}, {

"groupings" : [ ],

"key" : "0_6",

"label" : "December 2015",

"value" : "2015-12-01"

}, {

"groupings" : [ ],

"key" : "0_7",

"label" : "March 2016",

"value" : "2016-03-01"

} ],

"key" : "0",

"label" : "Manufacturing",

"value" : "Manufacturing"

}, {

"groupings" : [ {

"groupings" : [ ],

"key" : "1_0",

"label" : "February 2013",

"value" : "2013-02-01"

}, {

"groupings" : [ ],

"key" : "1_1",

"label" : "February 2015",

"value" : "2015-02-01"

}, {

"groupings" : [ ],

"key" : "1_2",

"label" : "September 2015",

"value" : "2015-09-01"

}, {

"groupings" : [ ],

"key" : "1_3",

"label" : "February 2016",

"value" : "2016-02-01"

}, {

"groupings" : [ ],

"key" : "1_4",

"label" : "April 2016",

"value" : "2016-04-01"

} ],

"key" : "1",

"label" : "Media",

"value" : "Media"

94

Return Details About Dashboard Components

Examples: Dashboards REST API Resources

}, {

"groupings" : [ {

"groupings" : [ ],

"key" : "2_0",

"label" : "November 2015",

"value" : "2015-11-01"

}, {

"groupings" : [ ],

"key" : "2_1",

"label" : "December 2015",

"value" : "2015-12-01"

}, {

"groupings" : [ ],

"key" : "2_2",

"label" : "March 2016",

"value" : "2016-03-01"

}, {

"groupings" : [ ],

"key" : "2_3",

"label" : "May 2016",

"value" : "2016-05-01"

}, {

"groupings" : [ ],

"key" : "2_4",

"label" : "June 2016",

"value" : "2016-06-01"

} ],

"key" : "2",

"label" : "Technology",

"value" : "Technology"

} ]

},

"hasDetailRows" : false,

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"s!AMOUNT" : {

"dataType" : "currency",

"label" : "Sum of Amount"

}

},

"detailColumnInfo" : { },

"groupingColumnInfo" : {

"INDUSTRY" : {

"dataType" : "picklist",

"groupingLevel" : 0,

"label" : "Industry"

},

"CLOSE_DATE" : {

"dataType" : "date",

"groupingLevel" : 0,

"label" : "Close Date"

}

},

}

95

Return Details About Dashboard Components

Examples: Dashboards REST API Resources Return Details About Dashboard Components

"reportMetadata" : {

"aggregates" : [ "s!AMOUNT" ],

"buckets" : [ {

"bucketType" : "picklist",

"devloperName" : "BucketField_47575792",

"label" : "Industry",

"nullTreatedAsZero" : false,

"otherBucketLabel" : null,

"sourceColumnName" : "INDUSTRY",

"values" : [ {

"label" : "Technology",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Agriculture", "Apparel", "Banking",

"Biotechnology", "Chemicals", "Communications", "Construction", "Consulting", "Education",

"Electronics" ]

}, {

"label" : "Energy",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Energy", "Engineering", "Entertainment",

"Environmental", "Finance", "Food & Beverage", "Government", "Healthcare", "Hospitality",

"Insurance", "Machinery", "Manufacturing" ]

}, {

"label" : "Healthcare",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Media", "Not For Profit", "Other", "Recreation",

"Retail", "Shipping", "Technology", "Telecommunications", "Transportation", "Utilities"

]

} ]

}, {

"bucketType" : "picklist",

"devloperName" : "BucketField_36625466",

"label" : "Stage",

"nullTreatedAsZero" : false,

"otherBucketLabel" : null,

"sourceColumnName" : "STAGE_NAME",

"values" : [ {

"label" : "Early",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Prospecting", "Qualification", "Needs Analysis"

]

}, {

"label" : "Late",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Value Proposition", "Id. Decision Makers",

"Perception Analysis", "Proposal/Price Quote", "Negotiation/Review" ]

}, {

"label" : "Won",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Closed Won" ]

}, {

"label" : "Lost",

"rangeUpperBound" : null,

"sourceDimensionValues" : [ "Closed Lost" ]

} ]

96

Examples: Dashboards REST API Resources

} ],

"chart" : null,

"crossFilters" : [ ],

"currency" : null,

"description" : null,

"detailColumns" : [ ],

"developerName" : "Pipeline_By_Industry1",

"division" : null,

"folderId" : "005R0000000Hv5rIAC",

"groupingsAcross" : [ ],

"groupingsDown" : [ {

"dateGranularity" : "None",

"name" : "INDUSTRY",

"sortAggregate" : null,

"sortOrder" : "Asc"

}, {

"dateGranularity" : "Month",

"name" : "CLOSE_DATE",

"sortAggregate" : null,

"sortOrder" : "Asc"

} ],

"hasDetailRows" : true,

"hasRecordCount" : false,

"historicalSnapshotDates" : [ ],

"id" : "00OR0000000OgsOMAS",

"name" : "Copy of Pipeline By Industry",

"reportBooleanFilter" : null,

"reportFilters" : [ {

"column" : "ACCOUNT_TYPE",

"isRunPageEditable" : false,

"operator" : "lessOrEqual",

"value" : "Integrator,Partner,Prospect"

}, {

"column" : "INDUSTRY",

"isRunPageEditable" : true,

"operator" : "notEqual",

"value" : ""

} ],

"reportFormat" : "SUMMARY",

"reportType" : {

"label" : "Opportunities",

"type" : "Opportunity"

},

"scope" : "organization",

"showGrandTotal" : true,

"showSubtotals" : true,

"sortBy" : [ ],

"standardDateFilter" : {

"column" : "CLOSE_DATE",

"durationValue" : "CUSTOM",

"endDate" : null,

"startDate" : null

},

"standardFilters" : [ {

97

Return Details About Dashboard Components

Examples: Dashboards REST API Resources

"name" : "open",

"value" : "all"

}, {

"name" : "probability",

"value" : ">0"

} ]

},

}

"status" : {

"dataStatus" : "DATA",

"errorCode" : null,

"errorMessage" : null,

"errorSeverity" : null,

"refreshDate" : "2016-03-22T18:24:39.000+0000",

"refreshStatus" : "IDLE"

}

} ],

"dashboardMetadata" : {

"canChangeRunningUser" : false,

"components" : [ {

"componentData" : 0,

"footer" : null,

"header" : "Pipeline This Quarter",

"id" : "01aR00000005aT4IAI",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

} ],

"autoSelectColumns" : false,

"filterColumns" : [ ],

"groupings" : null,

"maxRows" : null,

"sort" : null,

"useReportChart" : false,

"visualizationProperties" : {

"breakPoints" : [ {

"aggregateName" : "s!AMOUNT",

"breaks" : [ {

"color" : "c23934",

"lowerBound" : 0,

"upperBound" : 200000

}, {

"color" : "ffb75d",

"lowerBound" : 200000,

"upperBound" : 400000

}, {

"upperBound" : 600000

} ]

} ],

"color" : "00716b",

"lowerBound" : 400000,

"showPercentages" : true,

"showTotal" : true

},

Return Details About Dashboard Components

98

Examples: Dashboards REST API Resources

},

"visualizationType" : "Gauge"

"reportId" : "00OR0000000K2UeMAK",

"title" : null,

"type" : "Report"

}, {

"componentData" : 1,

"footer" : null,

"header" : "Pipeline by Industry",

"id" : "01aR00000005aT5IAI",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

} ],

"autoSelectColumns" : false,

"filterColumns" : [ ],

"groupings" : [ {

"name" : "INDUSTRY"

} ],

"maxRows" : null,

"sort" : {

"column" : "INDUSTRY",

},

"sortOrder" : "asc"

"useReportChart" : false,

"visualizationProperties" : {

"combineSmallGroups" : false,

"legendPosition" : "Bottom",

"showPercentages" : false,

"showTotal" : false,

"showValues" : false

},

"visualizationType" : "Donut"

},

"reportId" : "00OR0000000OgsOMAS",

"title" : null,

"type" : "Report"

} ],

"description" : null,

"developerName" : "yTtOilrkFGewFKpFUOscDuukUApfxH",

"filters" : [ ],

"folderId" : "00lR0000000DnRZIA0",

"id" : "01ZR00000008h2EMAQ",

"layout" : {

"components" : [ {

"colspan" : 3,

"column" : 0,

"row" : 0,

"rowspan" : 4

}, {

"colspan" : 3,

"column" : 0,

"row" : 4,

"rowspan" : 4

Return Details About Dashboard Components

99

Examples: Dashboards REST API Resources Get Dashboard Metadata

}

}

} ],

"gridLayout" : true,

"numColumns" : 9,

"rowHeight" : 80

},

"name" : "Liz's Sales Manager Dashboard",

"runningUser" : {

"displayName" : "Vandelay Art",

"id" : "005R0000000Hv5rIAC"

}

Get Dashboard Metadata

Get details about dashboard metadata using a GET request.

Use a GET request on the

Dashboard Describe

resource to get metadata for the specified dashboard, including dashboard components, filters, layout, and the running user.

Example Usage

/services/data/v37.0/analytics/dashboards/01ZR00000004SknMAE/describe

Example Response Body

{

"canChangeRunningUser" : true,

"components" : [ {

"componentData" : 0,

"footer" : null,

"header" : null,

"id" : "01aR00000005kCmIAI",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

} ],

"autoSelectColumns" : true,

"filterColumns" : [ {

"label" : "Closed",

"name" : "CLOSED"

}, {

"label" : "Account Type",

"name" : "ACCOUNT_TYPE"

}, {

"label" : "Annual Revenue",

"name" : "SALES"

} ],

"groupings" : [ {

"name" : "STAGE_NAME"

} ],

"maxRows" : null,

"sort" : {

"column" : "STAGE_NAME",

100

Examples: Dashboards REST API Resources

},

"sortOrder" : "asc"

"useReportChart" : false,

"visualizationProperties" : {

"axisRange" : {

"max" : null,

"min" : null,

"rangeType" : "auto"

},

"groupByType" : "cumulative",

"legendPosition" : "Bottom",

},

"showValues" : false

},

"visualizationType" : "Line"

"reportId" : "00OR0000000JizXMAS",

"title" : null,

"type" : "Report"

}, {

"componentData" : 1,

"footer" : null,

"header" : null,

"id" : "01aR00000005awVIAQ",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

} ],

"autoSelectColumns" : true,

"filterColumns" : [ {

"label" : "Closed",

"name" : "CLOSED"

}, {

"label" : "Account Type",

"name" : "ACCOUNT_TYPE"

}, {

"label" : "Annual Revenue",

"name" : "SALES"

} ],

"groupings" : [ {

"name" : "STAGE_NAME"

} ],

"maxRows" : null,

"sort" : {

"column" : "STAGE_NAME",

},

"sortOrder" : "asc"

"useReportChart" : false,

"visualizationProperties" : {

"combineSmallGroups" : true,

"legendPosition" : "Bottom",

"showPercentages" : false,

},

"showValues" : true

"visualizationType" : "Funnel"

101

Get Dashboard Metadata

Examples: Dashboards REST API Resources

},

"reportId" : "00OR0000000OFXeMAO",

"title" : null,

"type" : "Report"

}, {

"componentData" : 2,

"footer" : null,

"header" : null,

"id" : "01aR00000005awTIAQ",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

} ],

"autoSelectColumns" : true,

"filterColumns" : [ {

"label" : "Closed",

"name" : "CLOSED"

}, {

"label" : "Account Type",

"name" : "ACCOUNT_TYPE"

}, {

"label" : "Annual Revenue",

"name" : "SALES"

} ],

"groupings" : null,

"maxRows" : null,

"sort" : null,

"useReportChart" : false,

"visualizationProperties" : {

"breakPoints" : [ {

"aggregateName" : "s!AMOUNT",

"breaks" : [ {

"color" : "c25454",

"lowerBound" : 100000,

"upperBound" : 300000

}, {

"color" : "c2c254",

"lowerBound" : 300000,

"upperBound" : 800000

}, {

"color" : "54c254",

"lowerBound" : 800000,

"upperBound" : 1000000

} ]

} ],

"showPercentages" : false,

},

"showTotal" : false

},

"visualizationType" : "Gauge"

"reportId" : "00OR0000000JizXMAS",

"title" : null,

"type" : "Report"

}, {

102

Get Dashboard Metadata

Examples: Dashboards REST API Resources

"componentData" : 3,

"footer" : null,

"header" : null,

"id" : "01aR00000005kCnIAI",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

}, {

"name" : "a!AMOUNT"

} ],

"autoSelectColumns" : false,

"filterColumns" : [ {

"label" : "Closed",

"name" : "CLOSED"

}, {

"label" : "Account Type",

"name" : "ACCOUNT_TYPE"

}, {

"label" : "Annual Revenue",

"name" : "SALES"

} ],

"groupings" : [ {

"name" : "STAGE_NAME"

}, {

"name" : "TYPE"

} ],

"maxRows" : null,

"sort" : {

},

"column" : "STAGE_NAME",

"sortOrder" : "asc"

"useReportChart" : false,

"visualizationProperties" : {

"axisRange" : {

"max" : null,

"min" : null,

"rangeType" : "auto"

},

"groupByType" : "grouped",

},

"legendPosition" : "Bottom"

"visualizationType" : "Scatter"

},

"reportId" : "00OR0000000JizXMAS",

"title" : null,

"type" : "Report"

}, {

"componentData" : 4,

"footer" : null,

"header" : "My Table",

"id" : "01aR00000005awUIAQ",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

103

Get Dashboard Metadata

Examples: Dashboards REST API Resources

} ],

"autoSelectColumns" : false,

"filterColumns" : [ {

"label" : "Closed",

"name" : "CLOSED"

}, {

"label" : "Account Type",

"name" : "ACCOUNT_TYPE"

}, {

"label" : "Annual Revenue",

"name" : "SALES"

} ],

"groupings" : [ {

"name" : "INDUSTRY"

}, {

"name" : "CLOSE_DATE"

} ],

"maxRows" : null,

"sort" : {

"column" : "INDUSTRY",

},

"sortOrder" : "asc"

"useReportChart" : false,

"visualizationProperties" : {

"breakPoints" : [ {

"aggregateName" : "s!AMOUNT",

"breaks" : [ {

"color" : "c25454",

"lowerBound" : null,

"upperBound" : null

}, {

"color" : "c2c254",

"lowerBound" : null,

"upperBound" : null

}, {

"color" : "54c254",

"lowerBound" : null,

"upperBound" : null

} ]

} ],

"tableColumns" : [ {

"column" : "INDUSTRY",

"isPercent" : false,

"scale" : null,

"showTotal" : false,

"type" : "grouping"

}, {

"column" : "CLOSE_DATE",

"isPercent" : false,

"scale" : null,

"showTotal" : false,

"type" : "grouping"

}, {

"column" : "s!AMOUNT",

104

Get Dashboard Metadata

Examples: Dashboards REST API Resources

"isPercent" : false,

"scale" : null,

"showTotal" : true,

"type" : "aggregate"

},

} ]

},

"visualizationType" : "Table"

"reportId" : "00OR0000000OgsOMAS",

"title" : "My Table",

"type" : "Report"

}, {

"componentData" : 5,

"footer" : null,

"header" : null,

"id" : "01aR00000005kCoIAI",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

} ],

"autoSelectColumns" : false,

"filterColumns" : [ {

"label" : "Closed",

"name" : "CLOSED"

}, {

"label" : "Account Type",

"name" : "ACCOUNT_TYPE"

}, {

"label" : "Annual Revenue",

"name" : "SALES"

} ],

"groupings" : [ {

"name" : "STAGE_NAME"

}, {

"name" : "TYPE"

} ],

"maxRows" : null,

"sort" : {

"column" : "STAGE_NAME",

},

"sortOrder" : "asc"

"useReportChart" : false,

"visualizationProperties" : {

"aggregateVisualizationInfos" : [ {

"axis" : "Y2",

"visualizationType" : "Column"

} ],

"axisRange" : {

"max" : null,

"min" : null,

"rangeType" : "auto"

},

"groupByType" : "grouped",

"legendPosition" : "Bottom",

105

Get Dashboard Metadata

Examples: Dashboards REST API Resources

},

"showValues" : false

},

"visualizationType" : "Column"

"reportId" : "00OR0000000JizXMAS",

"title" : null,

"type" : "Report"

}, {

"componentData" : 6,

"footer" : null,

"header" : null,

"id" : "01aR00000005kCpIAI",

"properties" : {

"aggregates" : [ {

"name" : "s!AMOUNT"

}, {

"name" : "a!AMOUNT"

} ],

"autoSelectColumns" : false,

"filterColumns" : [ {

"label" : "Closed",

"name" : "CLOSED"

}, {

"label" : "Account Type",

"name" : "ACCOUNT_TYPE"

}, {

"label" : "Annual Revenue",

"name" : "SALES"

} ],

"groupings" : [ {

"name" : "STAGE_NAME"

} ],

"maxRows" : null,

"sort" : {

"column" : "STAGE_NAME",

},

"sortOrder" : "asc"

"useReportChart" : false,

"visualizationProperties" : {

"axisRange" : {

"max" : null,

"min" : null,

"rangeType" : "auto"

},

"groupByType" : "none",

"legendPosition" : "Bottom",

},

"showValues" : false

},

"visualizationType" : "Bar"

"reportId" : "00OR0000000JizXMAS",

"title" : null,

"type" : "Report"

} ],

106

Get Dashboard Metadata

Examples: Dashboards REST API Resources

"description" : null,

"developerName" : "Filtered_Dashboard",

"filters" : [ {

"errorMessage" : null,

"id" : "0IBR00000004CElOAM",

"name" : "Closed",

"options" : [ {

"alias" : "Open",

"endValue" : null,

"id" : "0ICR00000004CG4OAM",

"operation" : "equals",

"startValue" : null,

"value" : "True"

}, {

"alias" : "Closed",

"endValue" : null,

"id" : "0ICR00000004CG5OAM",

"operation" : "equals",

"startValue" : null,

"value" : "False"

} ],

"selectedOption" : null

}, {

"errorMessage" : null,

"id" : "0IBR00000004CEmOAM",

"name" : "Account Type",

"options" : [ {

"alias" : null,

"endValue" : null,

"id" : "0ICR00000004CG6OAM",

"operation" : "equals",

"startValue" : null,

"value" : "Analyst"

}, {

"alias" : null,

"endValue" : null,

"id" : "0ICR00000004CG7OAM",

"operation" : "equals",

"startValue" : null,

"value" : "Competitor"

}, {

"alias" : null,

"endValue" : null,

"id" : "0ICR00000004CG8OAM",

"operation" : "equals",

"startValue" : null,

"value" : "Press,Prospect,Reseller"

}, {

"alias" : null,

"endValue" : null,

"id" : "0ICR00000004CG9OAM",

"operation" : "notEqual",

"startValue" : null,

"value" : "Other"

107

Get Dashboard Metadata

Examples: Dashboards REST API Resources

}

}, {

"alias" : "Outsiders",

"endValue" : null,

"id" : "0ICR00000004CGAOA2",

"operation" : "lessOrEqual",

"startValue" : null,

"value" : "Integrator,Partner,Prospect"

} ],

"selectedOption" : null

}, {

"errorMessage" : null,

"id" : "0IBR0000000007cOAA",

"name" : "Annual Revenue",

"options" : [ {

"alias" : null,

"endValue" : null,

"id" : "0ICR000000000A5OAI",

"operation" : "lessThan",

"startValue" : null,

"value" : "\"400,000\""

} ],

"selectedOption" : null

} ],

"folderId" : "00lR0000000DnRZIA0",

"id" : "01ZR00000004SknMAE",

"layout" : {

"columns" : [ {

"components" : [ 0, 1, 2 ]

}, {

"components" : [ 3, 4 ]

}, {

"components" : [ 5, 6 ]

} ],

},

"gridLayout" : false

"name" : "Filtered Dashboard",

"runningUser" : {

"displayName" : "Vandelay Art",

"id" : "005R0000000Hv5rIAC"

}

Clone a Dashboard

Creates a copy of a dashboard by sending a POST request to the Dashboard List resource.

Example

You want to clone dashboard 01ZR00000008gkvMAA and save it in a new folder with ID 00lR0000000DnRZIA0.

Clone a Dashboard

108

Examples: Dashboards REST API Resources Delete a Dashboard

This POST request

/services/data/v35.0/analytics/dashboards/?cloneId=01ZR00000008gkvMAA

to the

Dashboard List resource clones the dashboard.

{"folderId":"00lR0000000DnRZIA0"}

The response to the POST request returns the following details about the cloned dashboard.

{ "attributes" :

{ "dashboardId" : "01ZR00000004SZZMA2",

"dashboardName" : "Sales Manager Dashboard",

"statusUrl" : "/services/data/v35.0/analytics/dashboards/01ZR00000004SZZMA2/status",

"type" : "Dashboard" },

...

"folderId" : "00lR0000000DnRZIA0",

"id" : "01ZR00000004SZZMA2",

"layout" : {

"columns" : [

{ "components" : [ 0, 1, 2, 3 ] },

{ "components" : [ 4, 5, 6 ] },

{ "components" : [ 7 ] } ],

"gridLayout" : false },

"name" : "Sales Manager Dashboard",

"runningUser" : { "displayName" : "Fred Wiliamson", "id" : "005R0000000Hv5rIAC" }

}

Delete a Dashboard

Delete a dashboard by sending a DELETE request to the Dashboard Results resource. Deleted dashboards are moved to the Recycle Bin.

Example

This DELETE request

/services/data/v34.0/analytics/dashboards/01ZD00000007S89MAE

to the Dashboard

Results resource deletes the dashboard and returns a 204 HTTP response code with no content in the response body.

109

CHAPTER 4

Examples: Analytics Notifications REST API

In this chapter ...

•

Get Analytics

Notifications

•

Create an Analytics

Notification

•

Save Changes to an

Analytics Notification

•

Delete an Analytics

Notification

•

Check Limits for

Analytics

Notifications

Use the Analytics Notifications REST API to get, update, create, and delete notifications about reports and Wave assets.

110

Examples: Analytics Notifications REST API Get Analytics Notifications

Get Analytics Notifications

Return a list of analytics notifications using a GET request.

Use a GET request on the

Analytics Notification List

resource to return a list of analytics notifications.

Example Usage

/services/data/v38.0/analytics/notifications?source=lightningReportSubscribe

Parameter Description

source

Required for

GET

calls. Specifies what type of analytics notification to return. Valid values are:

•

lightningReportSubscribe

— report subscriptions

•

waveNotification

— Wave notifications recordId

Optional. Return notifications for a single record. Valid values are:

•

reportId

— Unique report ID

•

lensId

— Unique Wave lens ID

Example Response Body

[ {

"active" : true,

"createdDate" : "2016-08-08T04:14:12Z",

"deactivateOnTrigger" : false,

"id" : "0AuR00000004CYpKAM",

"lastModifiedDate" : "2016-08-08T04:14:12Z",

"name" : "Notification1",

"recordId" : "00OR0000000P7EgMAK",

"schedule" : {

"details" : {

},

"time" : 3

},

"frequency" : "daily"

"source" : "lightningReportSubscribe",

"thresholds" : [ {

"actions" : [ {

"configuration" : {

"recipients" : [ ]

},

"type" : "sendEmail"

} ],

"conditions" : null,

"type" : "always"

} ]

}, {

"active" : true,

"createdDate" : "2016-08-10T22:22:17Z",

"deactivateOnTrigger" : false,

"id" : "0AuR000000000KSKAY",

111

Examples: Analytics Notifications REST API

"lastModifiedDate" : "2016-08-11T23:16:01Z",

"name" : "Notification2",

"recordId" : "00OR0000000PCHYMA4",

"schedule" : {

"details" : {

"daysOfMonth" : [ 1, 2, 4 ],

},

"time" : 22

},

"frequency" : "monthly",

"frequencyType" : "specific"

"source" : "lightningReportSubscribe",

"thresholds" : [ {

"actions" : [ {

"configuration" : {

},

"recipients" : [ ]

"type" : "sendEmail"

} ],

"conditions" : null,

"type" : "always"

} ]

}, {

"active" : true,

"createdDate" : "2016-08-12T04:01:50Z",

"deactivateOnTrigger" : false,

"id" : "0AuR000000000KcKAI",

"lastModifiedDate" : "2016-08-12T04:16:34Z",

"name" : "Notification3",

"recordId" : "00OR0000000PBXEMA4",

"schedule" : {

"details" : {

"dayInWeek" : "mon",

"time" : 22,

"weekInMonth" : "third"

},

"frequency" : "monthly",

},

"frequencyType" : "relative"

"source" : "lightningReportSubscribe",

"thresholds" : [ {

"actions" : [ {

"configuration" : {

"recipients" : [ ]

},

"type" : "sendEmail"

"type" : "always"

} ]

} ]

} ],

"conditions" : null,

112

Get Analytics Notifications

Examples: Analytics Notifications REST API

Create an Analytics Notification

Create an Analytics Notification using a POST request.

Use a POST request on the Analytics Notification List resource to create an analytics notification.

Example Usage

/services/data/v38.0/analytics/notifications

Example Request Body

{

}

"active" : true,

"createdDate" : "",

"deactivateOnTrigger" : false,

"id" : "",

"lastModifiedDate" : "",

"name" : "New Notification",

"recordId" : "00OR0000000PD55MAG",

"schedule" : {

"details" : {

"time" : 3

},

"frequency" : "daily"

},

"source" : "lightningReportSubscribe",

"thresholds" : [ {

"actions" : [ {

"configuration" : {

},

"recipients" : [ ]

"type" : "sendEmail"

} ],

"conditions" : null,

"type" : "always"

} ]

Example Response Body

{

"active" : true,

"createdDate" : "2016-08-12T05:57:19Z",

"deactivateOnTrigger" : false,

"id" : "0AuR00000004CZTKA2",

"lastModifiedDate" : "2016-08-12T05:57:19Z",

"name" : "New Notification",

"recordId" : "00OR0000000PD55MAG",

"schedule" : {

"details" : {

},

"time" : 3

"frequency" : "daily"

},

"source" : "lightningReportSubscribe",

"thresholds" : [ {

113

Create an Analytics Notification

Examples: Analytics Notifications REST API Save Changes to an Analytics Notification

}

"actions" : [ {

"configuration" : {

},

"recipients" : [ ]

"type" : "sendEmail"

} ],

"conditions" : null,

"type" : "always"

} ]

Save Changes to an Analytics Notification

Save Changes to an Analytics Notification using a PUT request.

Use a PUT request on the Analytics Notification resource to save changes to an analytics notification.

Example Usage

/services/data/v38.0/analytics/notifications/

analytics notification ID

Example Request Body

In this example, an analytics notification is changed so that it runs daily at 9:00 AM instead of 3:00 AM.

{

}

"active" : true,

"createdDate" : "",

"deactivateOnTrigger" : false,

"id" : "0AuR00000004CZTKA2",

"lastModifiedDate" : "",

"name" : "New Notification",

"recordId" : "00OR0000000PD55MAG",

"schedule" : {

"details" : {

},

"time" : 9

"frequency" : "daily"

},

"source" : "lightningReportSubscribe",

"thresholds" : [ {

"actions" : [ {

"configuration" : {

"recipients" : [ ]

},

"type" : "sendEmail"

} ],

"conditions" : null,

"type" : "always"

} ]

114

Examples: Analytics Notifications REST API Delete an Analytics Notification

Example Response Body

The response body reflects the updated and saved analytics notifications.

{

"active" : true,

"createdDate" : "2016-08-12T05:57:19Z",

"deactivateOnTrigger" : false,

"id" : "0AuR00000004CZTKA2",

"lastModifiedDate" : "2016-08-12T06:12:24Z",

"name" : "New Notification",

"recordId" : "00OR0000000PD55MAG",

"schedule" : {

"details" : {

"time" : 9

},

"frequency" : "daily"

},

"source" : "lightningReportSubscribe",

"thresholds" : [ {

"actions" : [ {

"configuration" : {

},

"recipients" : [ ]

"type" : "sendEmail"

} ],

"conditions" : null,

"type" : "always"

} ]

}

Delete an Analytics Notification

Delete an Analytics Notification using a DELETE request. Once deleted, the analytics notification can't be recovered.

Use a DELETE request on the

Analytics Notification

resource to delete an analytics notification.

Example Usage

/services/data/v38.0/analytics/notifications/

analytics notification ID

The analytic notification deletes and returns a 204 HTTP response code with no content in the response body.

Check Limits for Analytics Notifications

Check analytics notification limits using a GET request.

Use a GET request on the

Analytics Notification Limits resource to check limits for analytics notifications.

Example Usage

/services/data/v38.0/analytics/notifications/limits?source=waveNotification

Method

GET

Description

Check how many analytic notifications you have, and the maximum number you can have.

115

Examples: Analytics Notifications REST API

Example Response Body

{

}

"userLimit" : {

"max" : 5,

"remaining" : 2

}

Check Limits for Analytics Notifications

116

CHAPTER 5

Reports API Resource Reference

In this chapter ...

•

Report

•

Describe

•

Execute Sync

•

Execute Async

•

Instances List

•

Instance Results

•

Report List

•

Query

•

Report Fields

•

Report Error Codes

Resources for the Reports API are available at

/services/data/

<latest API

version>/analytics/reports

. You can query each resource with a HTTP method (such as

GET). Use these resources to integrate report data directly into your applications.

Resource

Report

Describe

Execute Sync

Execute Async

Instances List

Instance Results

Report List

Supported

HTTP

Method

Description

PATCH

DELETE

GET

Saves changes to a report.

Deletes a report.

Gives report metadata. This includes information about fields that are defined in the report as detail columns, summaries, custom summary formulas, filters, and groupings.

GET

POST

POST

GET

GET

GET

POST

Gives report summary level data with or without details.

Returns specific results if you define dynamic filters, groupings, or aggregates in the metadata of a POST request.

Returns an instance that stores summary level data with or without details for a report run asynchronously. To get specific results, define filters in the metadata of the request.

List of instances of a report that were requested for an asynchronous run.

Depending on the type of your request, gives summary level data with or without details for an instance of a report run asynchronously.

List of reports that were recently viewed by the API user.

Makes a copy of a report.

Report Fields

POST If the request body is empty, returns a list of all possible report fields. Otherwise, returns a list of fields that specified reports share.

Use the fields

resource to determine the best fields for use in dashboard filters.

117

Reports API Resource Reference

Report

Saves changes to a report or deletes a report.

Resource URL

Data

Summary

URL

/services/data/

<latest API version>

/analytics/reports/<report ID>

Formats

JSON

HTTP Methods

Method

PATCH

DELETE

Description

Saves changes to a report. See this

example .

Deletes a report. See this

example .

PATCH Request Body

Property

aggregates buckets chart crossFilters

Type

Array of strings

Bucket field

Chart[]

Cross filter on page

137[]

Description

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

118

Report

Reports API Resource Reference

Property

customSummaryFormula currency

Type

Custom summary formula

String

Description

Describes a custom summary formulas.

detailColumns developerName division folderId groupingsAcross groupingsDown hasDetailRows

Array of strings

String

String

String

Groupings across[]

Groupings down[]

Boolean hasRecordCount

Boolean historicalSnapshotDates

Array of strings id name reportBooleanFilter

String

String

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.

Unique API names for the fields that have detailed data.

Report API name.

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.

ID of the folder that contains the report.

Note: 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.

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.

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

List of historical snapshot dates.

Unique report ID.

Display name of the report.

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

Report

119

Reports API Resource Reference

Property

reportFilters reportFormat reportType scope showGrandTotal showSubtotals

Type

Filter details[]

String

Report type

String

Boolean

Boolean

Description

exceeds 100K AND they are medium or large sized businesses. The filters are processed by the logic, “(1 OR 2) AND 3.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

},

{

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

•

SUMMARY

•

MATRIX

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.

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.

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

Report

120

Reports API Resource Reference

Property

sortBy standardDateFilter

Type

Array of strings

Array of strings standardFilters

Array of strings supportsRoleHierarchy

Boolean topRows

Top rows

userOrHierarchyFilterId

String

Description

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.

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.

Indicates whether the report type supports role hierarchy filtering (true) or not (false).

Describes a row limit filter applied to the report.

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.

PATCH Response Body

Property

reportMetadata reportTypeMetadata reportExtendedMetadata

Type

Report metadata

Report type metadata

Report extended metadata

Description

Unique identifiers for groupings and summaries.

Fields in each section of a report type plus filter information for those fields.

Additional information about summaries and groupings.

Report metadata

Property

aggregates

Type

Array of strings

Description

Unique identities for summary or custom summary formula fields in the report. For example:

•

a!Amount

represents the average for the

Amount

column.

Report

121

Reports API Resource Reference

Property

detailColumns developerName division

Type

buckets chart crossFilters customSummaryFormula currency

Bucket field

Chart[]

Cross filter

on page

128[]

Custom summary formula

String folderId groupingsAcross

Array of strings

String

String

String

Groupings across[]

Description

•

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

Describes a custom summary formulas.

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.

Unique API names for the fields that have detailed data.

Report API name.

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.

ID of the folder that contains the report.

Note: 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.

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.

Report

122

Reports API Resource Reference

Property

groupingsDown hasDetailRows hasRecordCount reportFilters reportFormat

Type

Groupings down[]

Boolean

Boolean historicalSnapshotDates

Array of strings id

String name reportBooleanFilter

String

String

Filter details[]

String

Description

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

List of historical snapshot dates.

Unique report ID.

Display name of the report.

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.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

},

{

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

Report

123

Reports API Resource Reference

Property

reportType scope showGrandTotal showSubtotals sortBy standardDateFilter standardFilters supportsRoleHierarchy topRows userOrHierarchyFilterId

Type

Report type

String

Boolean

Boolean

Array of strings

Array of strings

Array of strings

Boolean

Top rows

String

Description

•

SUMMARY

•

MATRIX

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.

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.

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.

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.

Indicates whether the report type supports role hierarchy filtering

(true) or not (false).

Describes a row limit filter applied to the report.

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.

Report

124

Reports API Resource Reference

Chart

Property

chartType groupings hasLegend showChartValues summaries summaryAxisLocations

String title

String

Groupings down

Property

name sortOrder

Type

String

String dateGranularity

Type

String

String

Boolean

Boolean

Array of strings

Description

Type of chart.

Report grouping.

Indicates whether the report has a legend.

Indicates whether the report shows chart values.

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.

Specifies the axis that shows the summary values. Valid values are

X

and

Y

.

Name of the chart.

String

Description

API name of the field used as a row grouping.

Order in which data is sorted within a row grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

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

125

Report

Reports API Resource Reference

Property

sortAggregate

Type

String

Description

•

Calendar Month in Year

•

Calendar Day in Month

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.

{

"aggregates": ["s!SALES","RowCount"],

"groupingsDown": [

{

"name": "USERS.NAME",

"sortOrder": "Desc",

"dateGranularity": "None",

"sortAggregate": "s!SALES"

}

]

}

Report

Groupings across

Property

name sortOrder

Type

String

String dateGranularity

String

Description

API name of the field used as a column grouping.

Order in which data is sorted within a column grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

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

126

Reports API Resource Reference

Filter details

Property

column isRunPageEditable operator value

Type

String

Boolean

String

String

Description

Unique API name for the field that’s being filtered.

Indicates if this is an editable filter in the user interface.

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 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

bucketType developerName label nullTreatedAsZero

Type

BucketType

String

String

Boolean

Description

The type of bucket. Possible values are number

, percent

, and picklist

API name of the bucket.

User-facing name of the bucket.

Specifies whether null values are converted to zero ( true

) or not

( false

).

127

Report

Reports API Resource Reference

Property

otherBucketLabel sourceColumnName values

Bucket field value

Property

label sourceDimensionValues

Type

String

String rangeUpperBound

Double

Description

The user-facing name of the bucket.

A list of the values from the source field included in this bucket category (in buckets of type

PICKLIST

and buckets of type

TEXT

).

The greatest range limit under which values are included in this bucket category (in buckets of type

NUMBER

).

Cross filter

Property

criteria includesObject primaryEntityField relatedEntity relatedEntityJoinField

Type Description

Array of

Filter details[]

Information about how to filter the relatedEntity

. Use to relate the primary entity with a subset of the relatedEntity

.

Boolean

String

String

String

Specifies whether objects returned have a relationship with the relatedEntity

(true) or not ( false

).

The name of the object on which the cross filter is evaluated.

The name of the object that the primaryEntityField

is evaluated against. (The right-hand side of the cross filter).

The name of the field used to join the primaryEntityField and relatedEntity

.

Custom summary formula

Property

label description formulaType decimalPlaces

Type

String

String

Array of

BucketTypeValues

Description

Name of the fields grouped as “Other” (in buckets of

BucketType

PICKLIST

).

Name of the bucketed field.

Describes the values included in the bucket field..

Type

String

String

String

Integer

Description

The user-facing name of the custom summary formula.

The user-facing description of the custom summary formula.

The format of the numbers in the custom summary formula. Possible values are number

, currency

, and percent

.

The number of decimal places to include in numbers.

Report

128

Reports API Resource Reference Describe

Property

downGroup downGroupType acrossGroup acrossGroupType formula

Top rows

Property

rowLimit direction

Type

String

String

String

String

String

Description

The name of a row grouping when the downGroupType

is

CUSTOM

.

Null

otherwise.

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The name of a column grouping when the accrossGroupType is

CUSTOM

.

Null

otherwise.

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The operations performed on values in the custom summary formula.

Type

Integer

String

Description

The number of rows returned in the report.

The sort order of the report rows.

Describe

Retrieves report, report type, and related metadata for a tabular, summary, or matrix report.

•

Report metadata gives information about the report as a whole. Tells you such things as, the report type, format, the fields that are summaries, row or column groupings, filters saved to the report, and so on.

•

Report type metadata tells you about all the fields available in the report type, those you can filter, and by what filter criteria.

•

Report extended metadata tells you about the fields that are summaries, groupings, and contain record details in the report. A property that displays null indicates that its value is not available.

Resource URL

/services/data/

<latest API version>

/analytics/reports/

<report ID>

/describe

Formats

JSON

HTTP Methods

Method

GET

Description

Retrieves report, report type, and related metadata for a tabular, summary, or matrix report. See this

example .

129

Reports API Resource Reference

Response Body

Property

reportMetadata reportTypeMetadata reportExtendedMetadata

Type

Report metadata

Report type metadata

Report extended metadata

Description

Unique identifiers for groupings and summaries.

Fields in each section of a report type plus filter information for those fields.

Additional information about summaries and groupings.

Describe

Report metadata

Property

aggregates detailColumns developerName division

Type

Array of strings buckets chart crossFilters customSummaryFormula currency

Bucket field

Chart[]

Cross filter

on page

137[]

Custom summary formula

String

Array of strings

String

String

Description

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

Describes a custom summary formulas.

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.

Unique API names for the fields that have detailed data.

Report API name.

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

130

Reports API Resource Reference Describe

Property

folderId groupingsAcross groupingsDown hasDetailRows hasRecordCount

Type

String

Groupings across[]

Groupings down[]

Boolean

Boolean historicalSnapshotDates

Array of strings id

String name reportBooleanFilter

String

String

Description

have the “Affected by Divisions” permission, your reports include records in all divisions.

ID of the folder that contains the report.

Note: 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.

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.

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

List of historical snapshot dates.

Unique report ID.

Display name of the report.

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.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

131

Reports API Resource Reference

Property

reportFilters reportFormat reportType scope

Type

Filter details[]

String

Report type

String showGrandTotal showSubtotals sortBy standardDateFilter

Boolean

Boolean

Array of strings

Array of strings

Describe

Description

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

•

SUMMARY

•

MATRIX

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.

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.

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.

132

Reports API Resource Reference

Property

standardFilters supportsRoleHierarchy topRows userOrHierarchyFilterId

Type

Array of strings

Boolean

Top rows

String

Describe

Description

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.

Indicates whether the report type supports role hierarchy filtering

(true) or not (false).

Describes a row limit filter applied to the report.

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

chartType groupings hasLegend showChartValues summaries summaryAxisLocations title

Type

String

String

Boolean

Boolean

Array of strings

String

String

Description

Type of chart.

Report grouping.

Indicates whether the report has a legend.

Indicates whether the report shows chart values.

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.

Specifies the axis that shows the summary values. Valid values are

X

and

Y

.

Name of the chart.

133

Reports API Resource Reference

Groupings down

Property

name sortOrder

Type

String

String dateGranularity

String sortAggregate

String

Describe

Description

API name of the field used as a row grouping.

Order in which data is sorted within a row grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

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

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.

{

"aggregates": ["s!SALES","RowCount"],

"groupingsDown": [

{

"name": "USERS.NAME",

"sortOrder": "Desc",

"dateGranularity": "None",

"sortAggregate": "s!SALES"

}

]

}

Groupings across

Property

name

Type

String

Description

API name of the field used as a column grouping.

134

Reports API Resource Reference

Property

sortOrder dateGranularity

Type

String

String

Describe

Description

Order in which data is sorted within a column grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

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

column isRunPageEditable operator

Type

String

Boolean

String

Description

Unique API name for the field that’s being filtered.

Indicates if this is an editable filter in the user interface.

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)

135

Reports API Resource Reference

Property

value

Type

String

Description

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.

Describe

Bucket field

Property

bucketType developerName label nullTreatedAsZero otherBucketLabel sourceColumnName values

Bucket field value

Property

label sourceDimensionValues

Type

String

String rangeUpperBound

Double

Type

BucketType

String

String

Boolean

String

String

Array of

BucketTypeValues

Description

The type of bucket. Possible values are number

, percent

, and picklist

API name of the bucket.

User-facing name of the bucket.

Specifies whether null values are converted to zero ( true

) or not

( false

).

Name of the fields grouped as “Other” (in buckets of

BucketType

PICKLIST

).

Name of the bucketed field.

Describes the values included in the bucket field..

Description

The user-facing name of the bucket.

A list of the values from the source field included in this bucket category (in buckets of type

PICKLIST

and buckets of type

TEXT

).

The greatest range limit under which values are included in this bucket category (in buckets of type

NUMBER

).

136

Reports API Resource Reference Describe

Cross filter

Property

criteria includesObject primaryEntityField relatedEntity relatedEntityJoinField

Type Description

Array of

Filter details[]

Information about how to filter the relatedEntity

. Use to relate the primary entity with a subset of the relatedEntity

.

Boolean Specifies whether objects returned have a relationship with the relatedEntity

(true) or not ( false

).

String

String

String

The name of the object on which the cross filter is evaluated.

The name of the object that the primaryEntityField

is evaluated against. (The right-hand side of the cross filter).

The name of the field used to join the primaryEntityField and relatedEntity

.

Custom summary formula

Property

label description formulaType decimalPlaces downGroup downGroupType acrossGroup acrossGroupType formula

Type

String

String

String

Integer

String

String

String

String

String

Description

The user-facing name of the custom summary formula.

The user-facing description of the custom summary formula.

The format of the numbers in the custom summary formula. Possible values are number

, currency

, and percent

.

The number of decimal places to include in numbers.

The name of a row grouping when the downGroupType

is

CUSTOM

.

Null

otherwise.

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The name of a column grouping when the accrossGroupType is

CUSTOM

.

Null

otherwise.

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The operations performed on values in the custom summary formula.

Top rows

Property

rowLimit direction

Type

Integer

String

Description

The number of rows returned in the report.

The sort order of the report rows.

137

Reports API Resource Reference Describe

Report type metadata

Property

categories dataTypeFilterOperatorMap

Type

Categories[]

Filter operator reference

Description

All fields in the report type organized by section.

Lists all the possible field data types that can be used to filter the report. Each data type, such as phone, percent, currency, or picklist has two properties: name

: Of type string, this is a unique API name for each field type’s filter criteria. Use this API name in the metadata to define filter criteria for a report.

label

: Of type string, this is the display name for each filter criteria available to fields of a particular data type. For example, multipicklist

fields can have for filter criteria, “equals,”

“not equal to,” “includes,” and “excludes.” Bucket fields are considered to be of string

data type.

divisionInfo scopeInfo

Division info[]

Scope info[]

Default division and list of all possible record-level divisions that can be used in a report.

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.

standardDateFilterDurationGroups

Standard date filter duration groups[]

List of standard date filters available in reports.

standardFilterInfos

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.

Categories

Property

label

Type

String columns

Column map

Description

Display name of a section in the report type under which fields are organized. For example, in an Accounts with Contacts custom report type,

Account General

is the display name of the section that has fields on general account information.

Information for all fields in the report type organized under a particular section’s unique API name.

138

Reports API Resource Reference

Division info

Property

defaultValue values

Type

String

String

Description

Users are assigned a default division that applies to their newly created accounts, leads, and custom objects that are enabled for divisions.

All division values. Division values have two properties: label

: Display name of a division.

name

: Unique API name of a division.

Column map

Property

label filterValues

Type

String

String array

String

Boolean

Description

Display name of a field.

All filter values for a field, if the field data type is of picklist, multi-select picklist, boolean, or checkbox. For example, checkbox fields always have a value of

True

or

False

. For fields of other data types, the filter value is an empty array because their values can’t be determined. Filter values have two properties: name

: Unique API name for a filter value. Of type string.

label

: Display name of a filter value. Of type string.

Data type of the field.

False

means that the field is of a type that can’t be filtered. For example, fields of the type

Encrypted Text

can’t be filtered.

dataType filterable

Scope Info

Property

defaultValue values

Type

String

Array of strings

Description

Default scope of the data on which you run the report.

All scope values. Valid values depend on the report type. Scope values have the following properties: allowsDivision

: Allows you to segment the report by this scope.

label

: Display name of the scope.

value

: Value of the scope.

Describe

139

Reports API Resource Reference Describe

Standard date filter duration groups

Property

label

Type

String standardDateFilterDurations

Standard date filter durations[]

Description

Display name of the standard date filter grouping. Valid values are Calendar Year, Calendar Quarter, Calendar Month, Calendar

Week, Fiscal Year, Fiscal Quarter, Day and custom value based on a user-defined date range.

Details about each possible relative date filter defined under the standard date filter grouping.

Standard date filter durations

Property

endDate label

Type

String

String startDate value

String

String

Description

End date of a date filter.

Display name of a date filter. Valid date filters are relative date filters—like

Current FY

and

Current FQ

—and custom date filters.

Start date of a date filter.

API name of a date filter. Valid date filters are relative date filters—like

THIS_FISCAL_YEAR

and

NEXT_FISCAL_QUARTER

—and custom date filters.

Report extended metadata

Property

aggregateColumnInfo detailColumnInfo groupingColumnInfo

Type

Aggregate column information

Detail column information

Grouping column information

Description

Includes all report summaries such as,

Record Count

,

Sum

,

Average

,

Max

,

Min

, and custom summary formulas. Contains values for each summary listed in the report metadata

aggregates .

Two properties for each field that has detailed data identified by its unique API name. The detailed data fields are also listed in the report metadata.

Map of each row or column grouping to its metadata. Contains values for each grouping identified in the

groupingsDown

and

groupingsAcross

list.

Aggregate column information

Property

label

Type

String

Description

Display name for record count, or the summarized or custom summary formula field.

140

Reports API Resource Reference

Property

dataType

Type

String acrossGroupingContext

String

Describe

Description

Data type of the summarized or custom summary formula field.

Column grouping in the report where the custom summary formula is displayed. As this example shows in the JSON response and in the custom summary formula editor of the matrix report, the custom summary formula is set at the grand summary level for the columns.

{

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"FORMULA1" : {

"label" : "Stalled Oppty Avg",

"dataType" : "Percent",

"acrossGroupingContext" :

"GRAND_SUMMARY",

"downGroupingContext" :

"GRAND_SUMMARY"

},

}

}

} downGroupingContext

String

141

Row grouping in the report where the custom summary formula is displayed. In this example, the custom summary formula for a summary report is displayed at the first grouping level This example is shown in both the JSON response and in the custom summary formula editor of the summary report.

{

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

...},

"FORMULA1" : {

"label" : "Average Won",

"dataType" : "Number",

"acrossGroupingContext" : null,

}

}

}

},

"downGroupingContext" : "TYPE"

Reports API Resource Reference

Property Type Description

Detail column information

Property

label dataType

Type

String

String

Description

The localized display name of a standard field, the ID of a custom field, or the API name of a bucket field that has detailed data.

The data type of the field that has detailed data. Possible values are:

•

string

•

boolean

•

double

•

int

•

percent

•

currency

•

date

•

datetime

•

time

•

picklist

•

multipicklist

•

id

•

reference

•

textarea

•

phone

•

combobox

•

url

•

email

•

html

Grouping column information

Property

label

Type

String

142

Description

Display name of the field or bucket field used for grouping.

Describe

Reports API Resource Reference

Property

dataType groupingLevel

Type

String

Integer

Execute Sync

Description

Data type of the field used for grouping. Possible values are:

•

string

•

boolean

•

double

•

int

•

percent

•

currency

•

date

•

datetime

•

time

•

picklist

•

multipicklist

•

id

•

reference

•

textarea

•

phone

•

combobox

•

url

•

email

•

html

Level of the grouping. Value can be:

•

0

,

1

, or

2

. Indicates first, second, or third row level grouping in summary reports.

•

0

or

1

. Indicates first or second row or column level grouping in a matrix report.

SEE ALSO:

Execute Sync

Execute Async

Execute Sync

Runs a report immediately with or without changing filters, groupings, or aggregates and returns the latest summary data with or without details for your level of access.

143

Reports API Resource Reference Execute Sync

Resource URL

/services/data/

<latest API version>

/analytics/reports/

<report ID>

Formats

JSON

HTTP Methods

Method

GET

POST

Description

Get report results. See this example

.

Get specific results by passing dynamic filters, groupings, and aggregates in the report metadata. See this

example

.

POST Request Body

Property

aggregates buckets chart crossFilters customSummaryFormula currency detailColumns

Type

Array of strings

Bucket field

Chart[]

Cross filter on page

137[]

Custom summary formula

String

Array of strings

Description

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

Describes a custom summary formulas.

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.

Unique API names for the fields that have detailed data.

144

Reports API Resource Reference Execute Sync

Property

developerName division folderId groupingsAcross groupingsDown hasDetailRows hasRecordCount historicalSnapshotDates id name reportBooleanFilter

Type

String

String

String

Groupings across[]

Groupings down[]

Boolean

Boolean

Array of strings

String

String

String

Description

Report API name.

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.

ID of the folder that contains the report.

Note:

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.

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.

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

List of historical snapshot dates.

Unique report ID.

Display name of the report.

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.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

145

Reports API Resource Reference

Property

reportFilters reportFormat reportType scope

Type

Filter details[]

String

Report type

String showGrandTotal showSubtotals sortBy standardDateFilter

Boolean

Boolean

Array of strings

Array of strings

Execute Sync

Description

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

},

{

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

•

SUMMARY

•

MATRIX

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.

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.

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.'

146

Reports API Resource Reference

Property

standardFilters supportsRoleHierarchy topRows userOrHierarchyFilterId

Type

Array of strings

Boolean

Top rows

String

Execute Sync

Description

startDate

: Start date.

endDate

: End date.

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.

Indicates whether the report type supports role hierarchy filtering (true) or not (false).

Describes a row limit filter applied to the report.

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.

Response Body

Property

attributes allData factMap groupingsAcross groupingsDown hasDetailRows

Type

Attributes

Boolean

Fact map

Groupings across

Groupings down

Boolean

Description

Key report attributes and child resource URLs.

When

True

, all report results are returned.

When

False

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

Note:

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

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

.

Collection of column groupings, keys, and their values.

Collection of row groupings, keys, and their values.

When true

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

When false

, the fact map returns summary values.

147

Reports API Resource Reference Execute Sync

Property

reportExtendedMetadata reportMetadata

Type

Report extended metadata

Report metadata

Description

Additional information about columns, summaries, and groupings.

Unique identifiers for groupings and summaries.

Attributes

Property

describeUrl instancesUrl type reportName reportId

Type

String

String

String

String

String

Description

Resource URL to get report metadata.

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.

API resource format.

Display name of the report.

Unique report ID.

Fact map

Property

rows aggregates

Type

Data cells[]

Aggregates[]

Description

Array of detailed report data listed in the order of the detail columns provided by the report metadata.

Summary level data including record count for a report.

Data cells

Property

value label

Type

Detail column info data type

Description

The value of a specified cell.

If the response is an empty string, then API version 36.0 and earlier returns null. API version 37.0 and later returns an empty string.

String Display name of the value as it appears for a specified cell in the report.

Aggregates

Property

value

Type

Number

Description

Numeric value of the summary data for a specified cell.

148

Reports API Resource Reference

Property

label

Groupings across

Property

groupings

Groupings

Property

value key label groupings dategroupings

Execute Sync

Type

String

Description

Formatted summary data for a specified cell.

Type

Groupings[]

Description

Information for each column grouping as a list.

Type

String

String

String

Array

Array

149

Description

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.

Unique identity for a row or column grouping. The identity is used

by the fact map

to specify data values within each grouping.

Display name of a row or column grouping. For date and time fields, the label is the localized date or time.

Second or third level row or column groupings. If there are none, the value is an empty array.

Start date and end date of the interval defined by date granularity

.

Reports API Resource Reference Execute Async

Groupings down

Property

groupings

Type

Groupings[]

Description

Information for each row grouping as a list.

SEE ALSO:

Describe

Execute Async

Execute Async

Runs an instance of a report asynchronously with or without filters and returns a handle that stores the results of the run. The results can contain summary data with or without details.

Resource URL

/services/data/

<latest API version>

/analytics/reports/

<report ID>

/instances

Formats

JSON

HTTP Methods

Method

POST

Description

Runs an instance of a report asynchronously. See this

example . Also see this

example of a GET request that returns a

list of asynchronous runs of a report.

POST Request Body

Property

aggregates

Type

Array of strings

Description

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.

150

Reports API Resource Reference Execute Async

Property

buckets chart crossFilters customSummaryFormula currency detailColumns developerName division folderId groupingsAcross groupingsDown hasDetailRows hasRecordCount

Type

Bucket field

Chart[]

Cross filter on page

137[]

Custom summary formula

String

Description

•

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

Describes a custom summary formulas.

Array of strings

String

String

String

Groupings across[]

Groupings down[]

Boolean

Boolean

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.

Unique API names for the fields that have detailed data.

Report API name.

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.

ID of the folder that contains the report.

Note: 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.

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.

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

151

Reports API Resource Reference

Property Type

historicalSnapshotDates

Array of strings id name reportBooleanFilter

String

String

String reportFilters reportFormat reportType

Filter details[]

String

Report type

Execute Async

Description

List of historical snapshot dates.

Unique report ID.

Display name of the report.

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.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

},

{

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

•

SUMMARY

•

MATRIX

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.

152

Reports API Resource Reference

Property

scope showGrandTotal showSubtotals sortBy standardDateFilter

Boolean

Boolean

Array of strings

Array of strings standardFilters

Type

String

Array of strings supportsRoleHierarchy

Boolean topRows

Top rows

userOrHierarchyFilterId

String

Execute Async

Description

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.

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.

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.

Indicates whether the report type supports role hierarchy filtering (true) or not (false).

Describes a row limit filter applied to the report.

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.

Response Body

Property

id status

Type

String

String

Description

Unique ID for an instance of a report that was run asynchronously.

•

New

if the report run has just been triggered through a request.

•

Success

if the report ran.

•

Running

if the report is being run.

153

Reports API Resource Reference Instances List

Property

url ownerId completionDate hasDetailRows requestDate

Type

String

String

Date, time string

Boolean

Description

•

Error

if the report run failed. The instance of a report run can return an error if, for example, your permission to access the report has been removed since you requested the run.

URL where results of the report run for that instance are stored. The value is null

if the report couldn’t be run because of an error.

API name of the user that created the instance.

Date, time when the instance of the report run finished. Only available if the report instance ran successfully or couldn’t be run because of an error. Date-time information is in ISO-8601 format.

•

When false

, indicates that summary level data was requested for the report instance.

•

When true

, indicates that detailed data, which includes summary level data, was requested for the report instance.

Date, time string

Date and time when an instance of the report run was requested. Date-time information is in ISO-8601 format.

SEE ALSO:

Describe

Execute Sync

Instances List

Returns a list of instances for a report that you requested to be run asynchronously. Each item in the list is treated as a separate instance of the report run with metadata in that snapshot of time.

Resource URL

/services/data/

<latest API version>

/analytics/reports/

<report ID>

/instances

Formats

JSON

HTTP Methods

Method

GET

Description

Return a list of asynchronous runs of a report. See this example

.

154

Reports API Resource Reference

Response Body

Property

id

Type

String status

String url ownerId hasDetailRows

String

String

Boolean completionDate

Date, time string requestDate

Date, time string

Instance Results

Description

Unique ID for a report instance that was requested for a run. The ID is used to obtain results of the report run for that instance.

•

New

if the report run has just been triggered through a POST request.

•

Success

if the report ran.

•

Running

if the report is being run.

•

Error

if the report run failed. The instance of a report run can return an error if, for example, your permission to access the report has been removed since you requested the run.

URL where results of the report run for that instance are stored. The value is null

if the report couldn’t be run because of an error.

API name of the user that created the instance.

•

When false

, indicates that summary level data was requested for the report run.

•

When true

, indicates that detailed data, which includes summary level data, was requested for the report run.

Date, time when the instance of the report run finished. Only available if the report instance ran successfully or couldn’t be run because of an error. Date-time information is in ISO-8601 format.

Date and time when an instance of the report run was requested. Date-time information is in ISO-8601 format.

SEE ALSO:

Execute Async

Instance Results

Instance Results

Retrieves results for an instance of a report run asynchronously with or without filters. Depending on your asynchronous report run request, data can be at the summary level or include details.

Resource URL

/services/data/

<latest API version>

/analytics/reports/

<report ID>

/instances/

<instance

ID>

155

Reports API Resource Reference Instance Results

Formats

JSON

HTTP Methods

Method

GET

DELETE

Description

Retrieves results of an asynchronous report run. See this example

.

If the given report instance has a status

of

Success

or

Error

, delete the report instance and return an empty response body.

GET Response Body

Property

hasDetailRows allData

Type

Boolean

Boolean reportMetadata factMap groupingsDown groupingsAcross

Report metadata

Fact map

attributes

Attributes

reportExtendedMetadata

Report extended metadata

Groupings down

Groupings across

Description

•

When false

, report results are at summary level.

•

When true

, report results are at the record detail level.

When

True

, all report results are returned.

When

False

, detailed data for the first 2000 report rows are returned.

Information about the fields used to build the report.

Collection of summary level data or both detailed and summary level data.

Attributes for the instance of the report run.

Information on report groupings, summary fields, and detailed data columns, which is available if detailed data is requested.

Collection of row groupings.

Collection of column groupings.

Attributes

Property

id status

Type

String

String

Description

Unique ID for an instance of a report that was run.

•

New

if the report run has just been triggered through a request.

•

Success

if the report ran.

•

Running

if the report is being run.

•

Error

if the report run failed. The instance of a report run can return an error if, for example, your permission to access the report has been removed since you requested the run.

156

Reports API Resource Reference Report List

Property

ownerId completionDate requestDate type reportId reportName

Type

String

Date, time string

Date, time string

String

String

String

Description

API name of the user that created the instance.

Date, time when the instance of the report run finished. Only available if the report instance ran successfully or couldn’t be run because of an error.

Date-time information is in ISO-8601 format.

Date and time when an instance of the report run was requested. Date-time information is in ISO-8601 format.

Format of the resource.

Unique report ID.

Display name of the report.

SEE ALSO:

Execute Async

Instances List

Report List

Displays a list of up to 200 tabular, matrix, or summary reports that you recently viewed. To get a full list of reports by format, name, and other fields, use a SOQL query on the Report object. The resource can also be used to make a copy of a report.

Resource URL

Task

List reports

URL

/services/data/

<latest API version>

/analytics/reports

Copy report

/services/data/

<latest API version>

/analytics/reports?cloneId=<report ID>

Formats

JSON

HTTP Methods

Method

GET

Description

List of reports that were recently viewed by the API user. See this example

.

157

Reports API Resource Reference

Method

POST

Description

Create or clone a report.

To create a new report, see this

example .

To clone an existing report, see this

example .

Report List

GET Response Body

Property

name id url describeUrl instancesUrl

Type

String

String

String

String

String

Description

Report display name.

Unique report ID.

URL that returns report data.

URL that retrieves report metadata.

Information for each instance of the report that was run asynchronously.

POST Response Body

Property

aggregates buckets chart crossFilters customSummaryFormula

Type

Array of strings

Bucket field

Chart[]

Cross filter on page

137[]

Custom summary formula

Description

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

Describes a custom summary formulas.

158

Reports API Resource Reference Report List

Property

currency detailColumns developerName division folderId groupingsAcross groupingsDown hasDetailRows

Type

String

Array of strings

String

String

String

Groupings across[]

Groupings down[]

Boolean hasRecordCount

Boolean historicalSnapshotDates

Array of strings id name reportBooleanFilter

String

String

String

Description

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.

Unique API names for the fields that have detailed data.

Report API name.

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.

ID of the folder that contains the report.

Note: 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.

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.

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

List of historical snapshot dates.

Unique report ID.

Display name of the report.

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

159

Reports API Resource Reference

Property

reportFilters reportFormat reportType scope showGrandTotal showSubtotals

Type

Filter details[]

String

Report type

String

Boolean

Boolean

Report List

Description

exceeds 100K AND they are medium or large sized businesses. The filters are processed by the logic, “(1 OR 2) AND 3.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

},

{

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

•

SUMMARY

•

MATRIX

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.

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.

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

160

Reports API Resource Reference

Property

sortBy standardDateFilter

Type

Array of strings

Array of strings standardFilters

Array of strings supportsRoleHierarchy

Boolean topRows

Top rows

userOrHierarchyFilterId

String

Description

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.

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.

Indicates whether the report type supports role hierarchy filtering (true) or not (false).

Describes a row limit filter applied to the report.

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.

Query

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

Resource URL

/services/data/

<latest API version>

/analytics/reports/query

Formats

JSON

HTTP Methods

Method

POST

Description

Run a report without creating or saving the report. Customize your report using reportMetadata

that you specify in the request body. See this

example on page 58.

161

Query

Reports API Resource Reference

Request Body

Report metadata

Property

aggregates detailColumns developerName division folderId

Type

Array of strings buckets chart crossFilters customSummaryFormula currency

Bucket field

Chart[]

Cross filter

on page

168[]

Custom summary formula

String

Array of strings

String

String

String

Description

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

Describes a custom summary formulas.

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.

Unique API names for the fields that have detailed data.

Report API name.

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.

ID of the folder that contains the report.

Note: 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.

Query

162

Reports API Resource Reference

Property

groupingsAcross groupingsDown hasDetailRows hasRecordCount historicalSnapshotDates id name reportBooleanFilter

Type

Groupings across[]

Groupings down[]

Boolean

Boolean

Array of strings

String

String

String

Description

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.

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

List of historical snapshot dates.

Unique report ID.

Display name of the report.

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.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

},

{

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

Query

163

Reports API Resource Reference

Property

reportFilters reportFormat reportType scope showGrandTotal showSubtotals sortBy standardDateFilter standardFilters supportsRoleHierarchy topRows

Type

Filter details[]

String

Report type

String

Boolean

Boolean

Array of strings

Array of strings

Array of strings

Boolean

Top rows

Description

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

•

SUMMARY

•

MATRIX

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.

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.

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.

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.

Indicates whether the report type supports role hierarchy filtering

(true) or not (false).

Describes a row limit filter applied to the report.

Query

164

Reports API Resource Reference

Property

userOrHierarchyFilterId

Type

String

Description

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

chartType groupings hasLegend showChartValues summaries summaryAxisLocations

String title

String

Groupings down

Property

name sortOrder

Type

String

String

Type

String

String

Boolean

Boolean

Array of strings

Description

Type of chart.

Report grouping.

Indicates whether the report has a legend.

Indicates whether the report shows chart values.

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.

Specifies the axis that shows the summary values. Valid values are

X

and

Y

.

Name of the chart.

Description

API name of the field used as a row grouping.

Order in which data is sorted within a row grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

Query

165

Reports API Resource Reference

Property

dateGranularity sortAggregate

Type

String

String

Description

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

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.

{

"aggregates": ["s!SALES","RowCount"],

"groupingsDown": [

{

"name": "USERS.NAME",

"sortOrder": "Desc",

"dateGranularity": "None",

"sortAggregate": "s!SALES"

}

]

}

Query

Groupings across

Property

name sortOrder dateGranularity

Type

String

String

String

Description

API name of the field used as a column grouping.

Order in which data is sorted within a column grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

Interval set on a date field used as a column grouping. Value can be:

•

Day

166

Reports API Resource Reference

Property Type Description

•

Calendar Week

•

Calendar Month

•

Calendar Quarter

•

Calendar Year

•

Fiscal Quarter

•

Fiscal Year

•

Calendar Month in Year

•

Calendar Day in Month

Filter details

Property

column isRunPageEditable operator

Type

String

Boolean

String value

String

Description

Unique API name for the field that’s being filtered.

Indicates if this is an editable filter in the user interface.

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 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.

167

Query

Reports API Resource Reference

Bucket field

Property

bucketType developerName label nullTreatedAsZero otherBucketLabel sourceColumnName values

Bucket field value

Property

label sourceDimensionValues

Type

String

String rangeUpperBound

Double

Type

BucketType

String

String

Boolean

String

String

Array of

BucketTypeValues

Description

The type of bucket. Possible values are number

, percent

, and picklist

API name of the bucket.

User-facing name of the bucket.

Specifies whether null values are converted to zero ( true

) or not

( false

).

Name of the fields grouped as “Other” (in buckets of

BucketType

PICKLIST

).

Name of the bucketed field.

Describes the values included in the bucket field..

Description

The user-facing name of the bucket.

A list of the values from the source field included in this bucket category (in buckets of type

PICKLIST

and buckets of type

TEXT

).

The greatest range limit under which values are included in this bucket category (in buckets of type

NUMBER

).

Cross filter

Property

criteria includesObject primaryEntityField relatedEntity relatedEntityJoinField

Type Description

Array of

Filter details[]

Information about how to filter the relatedEntity

. Use to relate the primary entity with a subset of the relatedEntity

.

Boolean Specifies whether objects returned have a relationship with the relatedEntity

(true) or not ( false

).

String

String

String

The name of the object on which the cross filter is evaluated.

The name of the object that the primaryEntityField

is evaluated against. (The right-hand side of the cross filter).

The name of the field used to join the primaryEntityField and relatedEntity

.

Query

168

Reports API Resource Reference

Custom summary formula

Property

label description formulaType decimalPlaces downGroup downGroupType acrossGroup acrossGroupType formula

Top rows

Property

rowLimit direction

Response Body

Property

attributes allData

String

String

String

Type

String

String

String

Integer

String

String

Type

Integer

String

Description

The user-facing name of the custom summary formula.

The user-facing description of the custom summary formula.

The format of the numbers in the custom summary formula. Possible values are number

, currency

, and percent

.

The number of decimal places to include in numbers.

The name of a row grouping when the downGroupType

is

CUSTOM

.

Null

otherwise.

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The name of a column grouping when the accrossGroupType is

CUSTOM

.

Null

otherwise.

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The operations performed on values in the custom summary formula.

Description

The number of rows returned in the report.

The sort order of the report rows.

Type

Attributes

Boolean

Description

Key report attributes and child resource URLs.

When

True

, all report results are returned.

When

False

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

Note:

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

Query

169

Reports API Resource Reference

Property

factMap groupingsAcross groupingsDown hasDetailRows reportExtendedMetadata reportMetadata

Type

Fact map

Groupings across

Groupings down

Boolean

Description

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

.

Collection of column groupings, keys, and their values.

Collection of row groupings, keys, and their values.

When true

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

When false

, the fact map returns summary values.

Additional information about columns, summaries, and groupings.

Report extended metadata

Report metadata

Unique identifiers for groupings and summaries.

Attributes

Property

describeUrl instancesUrl type reportName reportId

Type

String

String

String

String

String

Description

Resource URL to get report metadata.

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.

API resource format.

Display name of the report.

Unique report ID.

Fact map

Property

rows aggregates

Type

Data cells[]

Aggregates[]

Description

Array of detailed report data listed in the order of the detail columns provided by the report metadata.

Summary level data including record count for a report.

Query

170

Reports API Resource Reference

Data cells

Property

value label

Aggregates

Property

value label

Groupings across

Property

groupings

Groupings

Property

value

Type

Detail column info data type

Description

The value of a specified cell.

If the response is an empty string, then API version 36.0 and earlier returns null. API version 37.0 and later returns an empty string.

String Display name of the value as it appears for a specified cell in the report.

Type

Number

String

Description

Numeric value of the summary data for a specified cell.

Formatted summary data for a specified cell.

Type

Groupings[]

Description

Information for each column grouping as a list.

Type

String

171

Description

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.

Query

Reports API Resource Reference

Property

key label groupings dategroupings

Type

String

String

Array

Array

Report Fields

Description

•

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.

Unique identity for a row or column grouping. The identity is used

by the fact map

to specify data values within each grouping.

Display name of a row or column grouping. For date and time fields, the label is the localized date or time.

Second or third level row or column groupings. If there are none, the value is an empty array.

Start date and end date of the interval defined by date granularity

.

Groupings down

Property

groupings

Type

Groupings[]

Description

Information for each row grouping as a list.

Report Fields

The Report Fields resource returns report fields available for specified reports. Use the resource to determine the best fields for use in dashboard filters by seeing which fields different source reports have in common. Available in API version 40.0 and later.

Resource URL

/services/data/

<latest API version>

/analytics/reports/

<report ID>

/fields

Formats

JSON

HTTP Methods

Method

POST

Description

If the request body is empty, returns a list of all possible report fields. Otherwise, returns a list of fields that specified reports share.

172

Reports API Resource Reference

POST Request Body

Property

intersectWith

Type

Array of Report IDs

Description

An array of unique report IDs.

Report Fields

POST Response Body

Property

displayGroups

Type

Array of Fields equivalentFields

Array of Fields equivalentFieldIndices

Map of Fields mergedGroups

Array of Fields

Description

Fields available when adding a filter.

Fields available for each specified report. Each object in this array is a list of common fields categorized by report type.

Map of each field’s API name to the index of the field in the equivalentFields

array.

Merged fields.

Example Request Body

{

"intersectWith": ["00OR0000000P3RVMA0"]

}

Example Response Body

{

"displayGroups" : {

"Opportunity" : [ {

"columns" : {

"ACCOUNT_CREATED_DATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Account: Created Date",

"maxLength" : null

},

"ACCOUNT_LAST_ACTIVITY" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Account: Last Activity",

},

"maxLength" : null

"ACCOUNT_LAST_UPDATE" : {

173

Reports API Resource Reference

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Account: Last Modified Date",

"maxLength" : null

},

"ACCOUNT_OWNER" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Account Owner",

},

"maxLength" : null

"ACCOUNT_OWNER_ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Account Owner Alias",

"maxLength" : 8

},

}

"label" : "Account: General",

"labelSuffix" : "(Opportunities)"

}, {

"columns" : {

"CLOSE_DATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Close Date",

"maxLength" : null

},

"CLOSE_DATE2" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Close Date (2)",

},

"maxLength" : null

"CLOSE_MONTH" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Close Month",

"maxLength" : null

},

"CREATED_ALIAS" : {

"dataType" : "string",

174

Report Fields

Reports API Resource Reference

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Created Alias",

},

"maxLength" : 8

"CREATED" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Created By",

"maxLength" : null

},

"CREATED_DATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Created Date",

},

"maxLength" : null

"LAST_ACTIVITY" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Last Activity",

},

"maxLength" : null

"LAST_UPDATE_BY_ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Last Modified Alias",

"maxLength" : 8

},

"LAST_UPDATE_BY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Last Modified By",

},

"maxLength" : null

"LAST_UPDATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

},

"label" : "Last Modified Date",

"maxLength" : null

175

Report Fields

Reports API Resource Reference

"LAST_STAGE_CHANGE_DATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Last Stage Change Date",

"maxLength" : null

}

},

"label" : "Opportunity Information",

"labelSuffix" : "(Opportunities)"

}, {

"columns" : {

"FULL_NAME" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Opportunity Owner",

"maxLength" : null

},

"OWNER_MANAGER" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Opportunity Owner: Manager",

"maxLength" : null

},

"ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Opportunity Owner Alias",

},

"maxLength" : 8

"ROLLUP_DESCRIPTION" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Owner Role",

"maxLength" : 80

},

}

"label" : "Opportunity Owner Information",

"labelSuffix" : "(Opportunities)"

} ],

"LeadList" : [ {

"columns" : {

"EMAIL_BOUNCED_DATE" : {

"dataType" : "datetime",

"filterValues" : [ ],

176

Report Fields

Reports API Resource Reference

"filterable" : true,

"isLookup" : false,

"label" : "Email Bounced Date",

"maxLength" : null

},

}

"label" : "Lead: Ph/Fax/Email",

"labelSuffix" : "(Leads)"

}, {

"columns" : {

"CREATED_ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Created Alias",

"maxLength" : 8

},

"CREATED_DATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Create Date",

},

"maxLength" : null

"CREATED" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Created By",

"maxLength" : null

},

"CREATED_MONTH" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

},

"label" : "Created Month",

"maxLength" : null

"LAST_ACTIVITY" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : false,

"label" : "Last Activity",

},

"maxLength" : null

"LAST_UPDATE" : {

"dataType" : "date",

"filterValues" : [ ],

"filterable" : true,

177

Report Fields

Reports API Resource Reference

"isLookup" : false,

"label" : "Last Modified",

},

"maxLength" : null

"LAST_UPDATE_BY_ALIAS" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Last Modified Alias",

"maxLength" : 8

},

"LAST_UPDATE_BY" : {

"dataType" : "string",

"filterValues" : [ ],

},

"filterable" : true,

"isLookup" : false,

"label" : "Last Modified By",

"maxLength" : null

"OWNER_ROLE_DISPLAY" : {

"dataType" : "string",

"filterValues" : [ ],

"filterable" : true,

"isLookup" : true,

"label" : "Owner Role Display",

"maxLength" : 80

}

},

"label" : "Lead General",

"labelSuffix" : "(Leads)"

},

} ]

"equivalentFieldIndices" : {

"ACCOUNT_CREATED_DATE" : 19,

"ACCOUNT_LAST_UPDATE" : 19,

"ACCOUNT_OWNER" : 15,

"CREATED_ALIAS" : 16,

"CREATED_DATE" : 19,

"LAST_UPDATE_BY_ALIAS" : 16,

"ALIAS" : 16,

"EMAIL_BOUNCED_DATE" : 19,

"CLOSE_MONTH" : 17,

"LAST_UPDATE_BY" : 15,

"CREATED_MONTH" : 17,

"LAST_ACTIVITY" : 17,

"ACCOUNT_LAST_ACTIVITY" : 17,

"CLOSE_DATE" : 17,

"CREATED" : 15,

"LAST_UPDATE" : 19,

"CLOSE_DATE2" : 17,

"OWNER_MANAGER" : 15,

"LAST_STAGE_CHANGE_DATE" : 19,

"ROLLUP_DESCRIPTION" : 7,

178

Report Fields

Reports API Resource Reference

"FULL_NAME" : 15,

"ACCOUNT_OWNER_ALIAS" : 16,

},

"OWNER_ROLE_DISPLAY" : 7

"equivalentFields" : [ {

"LeadList" : [ {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

} ],

"Opportunity" : [ {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

}, {

"name" : "FULL_NAME"

}, {

"name" : "OWNER_MANAGER"

}, {

"name" : "ACCOUNT_OWNER"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED_ALIAS"

}, {

"name" : "LAST_UPDATE_BY_ALIAS"

} ],

"Opportunity" : [ {

"name" : "CREATED_ALIAS"

}, {

"name" : "LAST_UPDATE_BY_ALIAS"

}, {

"name" : "ALIAS"

}, {

"name" : "ACCOUNT_OWNER_ALIAS"

} ]

}, {

"LeadList" : [ {

"name" : "LAST_UPDATE_BY"

}, {

"name" : "CREATED"

} ],

"Opportunity" : [ {

"name" : "LAST_UPDATE_BY"

}, {

"name" : "CREATED"

}, {

"name" : "FULL_NAME"

}, {

"name" : "OWNER_MANAGER"

}, {

"name" : "ACCOUNT_OWNER"

} ]

}, {

179

Report Fields

Reports API Resource Reference

"LeadList" : [ {

"name" : "LAST_UPDATE_BY_ALIAS"

}, {

"name" : "CREATED_ALIAS"

} ],

"Opportunity" : [ {

"name" : "LAST_UPDATE_BY_ALIAS"

}, {

"name" : "CREATED_ALIAS"

}, {

"name" : "ALIAS"

}, {

"name" : "ACCOUNT_OWNER_ALIAS"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_UPDATE"

}, {

"name" : "EMAIL_BOUNCED_DATE"

} ],

"Opportunity" : [ {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_STAGE_CHANGE_DATE"

}, {

"name" : "LAST_UPDATE"

}, {

"name" : "ACCOUNT_CREATED_DATE"

}, {

"name" : "ACCOUNT_LAST_UPDATE"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED_MONTH"

}, {

"name" : "LAST_ACTIVITY"

} ],

"Opportunity" : [ {

"name" : "CLOSE_DATE"

}, {

"name" : "CLOSE_DATE2"

}, {

"name" : "CLOSE_MONTH"

}, {

"name" : "LAST_ACTIVITY"

}, {

"name" : "ACCOUNT_LAST_ACTIVITY"

} ]

}, {

"LeadList" : [ {

"name" : "LAST_UPDATE"

}, {

180

Report Fields

Reports API Resource Reference

"name" : "CREATED_DATE"

}, {

"name" : "EMAIL_BOUNCED_DATE"

} ],

"Opportunity" : [ {

"name" : "LAST_UPDATE"

}, {

"name" : "LAST_STAGE_CHANGE_DATE"

}, {

"name" : "CREATED_DATE"

}, {

"name" : "ACCOUNT_CREATED_DATE"

}, {

"name" : "ACCOUNT_LAST_UPDATE"

} ]

}, {

"LeadList" : [ {

"name" : "OWNER_ROLE_DISPLAY"

} ],

"Opportunity" : [ {

"name" : "ROLLUP_DESCRIPTION"

} ]

}, {

"LeadList" : [ {

"name" : "LAST_ACTIVITY"

}, {

"name" : "CREATED_MONTH"

} ],

"Opportunity" : [ {

"name" : "LAST_ACTIVITY"

}, {

"name" : "CLOSE_DATE"

}, {

"name" : "CLOSE_DATE2"

}, {

"name" : "CLOSE_MONTH"

}, {

"name" : "ACCOUNT_LAST_ACTIVITY"

} ]

}, {

"LeadList" : [ {

"name" : "EMAIL_BOUNCED_DATE"

}, {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_UPDATE"

} ],

"Opportunity" : [ {

"name" : "LAST_STAGE_CHANGE_DATE"

}, {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_UPDATE"

}, {

181

Report Fields

Reports API Resource Reference

"name" : "ACCOUNT_CREATED_DATE"

}, {

"name" : "ACCOUNT_LAST_UPDATE"

} ]

}, {

"LeadList" : [ {

"name" : "LAST_ACTIVITY"

}, {

"name" : "CREATED_MONTH"

} ],

"Opportunity" : [ {

"name" : "CLOSE_DATE2"

}, {

"name" : "CLOSE_DATE"

}, {

"name" : "CLOSE_MONTH"

}, {

"name" : "LAST_ACTIVITY"

}, {

"name" : "ACCOUNT_LAST_ACTIVITY"

} ]

}, {

"LeadList" : [ {

"name" : "LAST_ACTIVITY"

}, {

"name" : "CREATED_MONTH"

} ],

"Opportunity" : [ {

"name" : "CLOSE_MONTH"

}, {

"name" : "CLOSE_DATE"

}, {

"name" : "CLOSE_DATE2"

}, {

"name" : "LAST_ACTIVITY"

}, {

"name" : "ACCOUNT_LAST_ACTIVITY"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

} ],

"Opportunity" : [ {

"name" : "FULL_NAME"

}, {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

}, {

"name" : "OWNER_MANAGER"

}, {

"name" : "ACCOUNT_OWNER"

182

Report Fields

Reports API Resource Reference

} ]

}, {

"LeadList" : [ {

"name" : "CREATED_ALIAS"

}, {

"name" : "LAST_UPDATE_BY_ALIAS"

} ],

"Opportunity" : [ {

"name" : "ALIAS"

}, {

"name" : "CREATED_ALIAS"

}, {

"name" : "LAST_UPDATE_BY_ALIAS"

}, {

"name" : "ACCOUNT_OWNER_ALIAS"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

} ],

"Opportunity" : [ {

"name" : "OWNER_MANAGER"

}, {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

}, {

"name" : "FULL_NAME"

}, {

"name" : "ACCOUNT_OWNER"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

} ],

"Opportunity" : [ {

"name" : "ACCOUNT_OWNER"

}, {

"name" : "CREATED"

}, {

"name" : "LAST_UPDATE_BY"

}, {

"name" : "FULL_NAME"

}, {

"name" : "OWNER_MANAGER"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED_ALIAS"

}, {

183

Report Fields

Reports API Resource Reference

"name" : "LAST_UPDATE_BY_ALIAS"

} ],

"Opportunity" : [ {

"name" : "ACCOUNT_OWNER_ALIAS"

}, {

"name" : "CREATED_ALIAS"

}, {

"name" : "LAST_UPDATE_BY_ALIAS"

}, {

"name" : "ALIAS"

} ]

}, {

"LeadList" : [ {

"name" : "LAST_ACTIVITY"

}, {

"name" : "CREATED_MONTH"

} ],

"Opportunity" : [ {

"name" : "ACCOUNT_LAST_ACTIVITY"

}, {

"name" : "CLOSE_DATE"

}, {

"name" : "CLOSE_DATE2"

}, {

"name" : "CLOSE_MONTH"

}, {

"name" : "LAST_ACTIVITY"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_UPDATE"

}, {

"name" : "EMAIL_BOUNCED_DATE"

} ],

"Opportunity" : [ {

"name" : "ACCOUNT_CREATED_DATE"

}, {

"name" : "LAST_STAGE_CHANGE_DATE"

}, {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_UPDATE"

}, {

"name" : "ACCOUNT_LAST_UPDATE"

} ]

}, {

"LeadList" : [ {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_UPDATE"

}, {

"name" : "EMAIL_BOUNCED_DATE"

184

Report Fields

Reports API Resource Reference Report Error Codes

}

} ],

"Opportunity" : [ {

"name" : "ACCOUNT_LAST_UPDATE"

}, {

"name" : "LAST_STAGE_CHANGE_DATE"

}, {

"name" : "CREATED_DATE"

}, {

"name" : "LAST_UPDATE"

}, {

"name" : "ACCOUNT_CREATED_DATE"

} ]

} ],

"mergedGroups" : { }

Report Error Codes

Errors can occur at the report level. Report-level error messages are returned in the response header.

When a report-level error occurs, the response header contains an HTTP response code and one of the following error messages:

Error Message

400

400

400

400

400

400

400

400

400

400

400

400

400

400

HTTP

Response

Code

400 The specified start date of <column name> specified for the standard date filter is invalid.

The specified end date of <column name> specified for the standard date filter is invalid.

The column <column name> specified for the standard date filter is invalid.

The column <column name> cannot be a standard date filter because it is not a date column.

The duration <value> specified for the standard date filter is invalid.

The report folder ID must be a valid folder ID.

The report folder ID can't be null.

The report name can't be null.

Column sorting isn't supported for matrix reports.

The sort column name must be from a selected column.

The sort column name can't be null.

A report can only be sorted by one column.

A snapshot date is not in the correct format. Accepted formats are one of the rolling dates defined or yyyy-MM-dd.

The request is invalid because reports that are not historical trending reports cannot have historical snapshot dates.

The request is invalid because there are no historical snapshot dates in the request body. Specify historical snapshot dates, or set historical snapshot dates as an empty array to omit them.

185

Reports API Resource Reference Report Error Codes

403

403

403

400

400

400

403

400

400

400

403

403

403

HTTP

Response

Code

400

Error Message

400

400

400

403

403

404

404

415

500

500

Only a report with fewer than 100 columns can be run. The columns are fields specified as detail columns, summaries, or custom summary formulas. Remove unneeded columns from the report and try again.

Can’t run the report because it doesn’t have any columns selected. Be sure to add fields as columns to the report through the user interface.

The request is invalid because there are no filters. Specify filters or set filters as an empty array to omit them.

The filter value for ID <value> is incorrect. Specify an ID that is 15 or 18 characters long, such as 006D000000CrRLw or 005U0000000Rg2CIAS.

Specify a valid filterable column because <value> is invalid.

Specify a valid condition because <value> is invalid.

Filter the date in the correct format. Accepted formats are yyyy-MM-dd'T'HH:mm:ss'Z' and yyyy-MM-dd.

The date formula is too large. Specify a reasonable value.

The request is invalid because there is no metadata. Specify metadata in the request body.

The clone request must contain a valid cloneId parameter.

The report can't be deleted because there are one or more dashboards referencing it.

You don't have permission to create reports in the given folder.

You don’t have permission to edit reports in the given folder.

The report definition is obsolete. Your administrator has disabled all reports for the custom object, or its relationships have changed.

You don’t have permission to run reports. Check that you have the Run Reports user permission.

You don’t have sufficient privileges to perform this operation.

Reports and Dashboards REST API can't process the request because it can accept only as many as <number> requests at a time to get results of reports run asynchronously.

Reports and Dashboards REST API can't process the request because it can accept only as many as <number> requests at a time to run reports synchronously.

You can't run more than <number> reports synchronously every 60 minutes. Try again later.

Use a valid URL, for example, /services/data/(apiversion)/analytics/reports/(reportID)/describe, to retrieve report metadata.

The data you’re trying to access is unavailable.

The Reports and Dashboards REST API only supports JSON content type in both request and response bodies. Specify requests with content type as application/json.

We ran into an error when fetching this report’s metadata. Try to re-submit your query.

We ran into an error when running this report. Try to re-submit your query.

186

Reports API Resource Reference Report Error Codes

500

500

500

501

501

HTTP

Response

Code

500

500

Error Message

The request body is either invalid or incomplete.

Results for this instance are unavailable because the report's metadata has changed from when the report was last run. To get results, run the report again or undo changes to the report's metadata.

The report failed to be deleted.

The report failed to be created.

The report failed to be saved.

You’re requesting data for an unsupported report format.

Historical trend data is unavailable in the report format requested. Change the report format to matrix and try again.

187

CHAPTER 6

Report Types API Resource Reference

In this chapter ...

•

Report Type List

•

Report Type

Use the Report Types API to get information about what report types are available in your org. The Report

Types API is available in API version 39.0 and later.

Resources for the Report Types API are available at

/services/data/

<latest API

version>/analytics/reporttypes

. You can query each resource with an

HTTP

method.

Resource Supported

HTTP

Method

Description

GET

Returns a list of available report types.

Report Type List

/services/data/

<latest API

version>/analytics/reportTypes

Report Type

/services/data/

<latest API

version>/analytics/reportType/<type>

GET

Returns metadata about a specified report type.

188

Report Types API Resource Reference

Report Type List

Return a list of report types.

Syntax

URI

/vXX.X/analytics/reportTypes

Formats

JSON

HTTP methods

Method

GET

Description

Returns a list of report types.

GET Response Body

An array of report type folder objects. Each object contains the following fields:

Property

label reportTypes

Type

String

reportTypes[]

Description

The end user-facing name of the report type folder.

An array of report types.

reportTypes[]

An array of report type objects. Each object contains the following fields:

Property

describeUrl label type

Type

String

String

String

Description

A URL link to the report type’s metadata.

The end user-facing name of the report type in the report builder.

The API name of the report type.

Report Type

Return metadata about a report type.

Syntax

URI

/vXX.X/analytics/reportTypes/

type

Report Type List

189

Report Types API Resource Reference Report Type

Formats

JSON

HTTP methods

Method

GET

Description

Return metadata about a report type

GET Request Body

A notification object with desired changes.

Property

reportMetadata reportTypeMetadata reportExtendedMetadata

Type

Report metadata

Report type metadata

Report extended metadata

Description

Unique identifiers for groupings and summaries.

Fields in each section of a report type plus filter information for those fields.

Additional information about summaries and groupings.

Report extended metadata

Property

aggregateColumnInfo detailColumnInfo groupingColumnInfo

Type

Aggregate column information

Detail column information

Grouping column information

Description

Includes all report summaries such as,

Record Count

,

Sum

,

Average

,

Max

,

Min

, and custom summary formulas. Contains values for each summary listed in the report metadata

aggregates .

Two properties for each field that has detailed data identified by its unique API name. The detailed data fields are also listed in the report metadata.

Map of each row or column grouping to its metadata. Contains values for each grouping identified in the

groupingsDown

and

groupingsAcross

list.

Aggregate column information

Property

label

Type

String dataType

String acrossGroupingContext

String

Description

Display name for record count, or the summarized or custom summary formula field.

Data type of the summarized or custom summary formula field.

Column grouping in the report where the custom summary formula is displayed. As this example shows in the JSON response and in the custom summary formula editor of the matrix report, the

190

Report Types API Resource Reference

Property Type

Report Type

Description

custom summary formula is set at the grand summary level for the columns.

{

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

"FORMULA1" : {

"label" : "Stalled Oppty Avg",

"dataType" : "Percent",

"acrossGroupingContext" :

"GRAND_SUMMARY",

"downGroupingContext" :

"GRAND_SUMMARY"

},

}

}

} downGroupingContext

String Row grouping in the report where the custom summary formula is displayed. In this example, the custom summary formula for a summary report is displayed at the first grouping level This example is shown in both the JSON response and in the custom summary formula editor of the summary report.

{

"reportExtendedMetadata" : {

"aggregateColumnInfo" : {

...},

"FORMULA1" : {

"label" : "Average Won",

"dataType" : "Number",

"acrossGroupingContext" : null,

}

}

}

},

"downGroupingContext" : "TYPE"

191

Report Types API Resource Reference

Detail column information

Property

label dataType

Type

String

String

Report Type

Description

The localized display name of a standard field, the ID of a custom field, or the API name of a bucket field that has detailed data.

The data type of the field that has detailed data. Possible values are:

•

string

•

boolean

•

double

•

int

•

percent

•

currency

•

date

•

datetime

•

time

•

picklist

•

multipicklist

•

id

•

reference

•

textarea

•

phone

•

combobox

•

url

•

email

•

html

Grouping column information

Property

label dataType

Type

String

String

192

Description

Display name of the field or bucket field used for grouping.

Data type of the field used for grouping. Possible values are:

•

string

•

boolean

•

double

•

int

•

percent

•

currency

Report Types API Resource Reference

Property Type

groupingLevel

Integer

Report Type

Description

•

date

•

datetime

•

time

•

picklist

•

multipicklist

•

id

•

reference

•

textarea

•

phone

•

combobox

•

url

•

email

•

html

Level of the grouping. Value can be:

•

0

,

1

, or

2

. Indicates first, second, or third row level grouping in summary reports.

•

0

or

1

. Indicates first or second row or column level grouping in a matrix report.

Report metadata

Property

aggregates buckets chart crossFilters

Type

Array of strings

Bucket field

Chart[]

Cross filter

on page

200[]

Description

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.

Describes a bucket field.

Details about the chart used in a report.

Cross filters applied to the report.

193

Report Types API Resource Reference Report Type

Property

customSummaryFormula currency

Type

Custom summary formula

String

Description

Describes a custom summary formulas.

detailColumns developerName division folderId groupingsAcross groupingsDown hasDetailRows hasRecordCount historicalSnapshotDates id name

Array of strings

String

String

String

Groupings across[]

Groupings down[]

Boolean

Boolean

Array of strings

String

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.

Unique API names for the fields that have detailed data.

Report API name.

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.

ID of the folder that contains the report.

Note: 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.

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.

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.

Indicates whether to include detailed data with the summary data.

Indicates whether the report shows the record count.

List of historical snapshot dates.

Unique report ID.

Display name of the report.

194

Report Types API Resource Reference

Property

reportBooleanFilter reportFilters reportFormat reportType scope

Type

String

Filter details[]

String

Report type

String

Report Type

Description

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.”

{

...

"reportBooleanFilter": "(1 OR 2) AND

3",

"reportFilters": [

{

"value":

"Analyst,Integrator,Press,Other",

"column": "TYPE",

"operator": "notEqual"

},

{

"value": "100,000",

"column": "SALES",

"operator": "greaterThan"

},

{

"value": "Small",

"column": "Size",

"operator": "notEqual"

}

]

}

}

List of each custom filter in the report along with the field name, filter operator, and filter value.

Format of the report. Value can be:

•

TABULAR

•

SUMMARY

•

MATRIX

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.

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.

195

Report Types API Resource Reference

Property

showGrandTotal showSubtotals sortBy standardDateFilter

Type

Boolean

Boolean

Array of strings

Array of strings standardFilters supportsRoleHierarchy topRows userOrHierarchyFilterId

Array of strings

Boolean

Top rows

String

Report Type

Description

Indicates whether the report shows the grand total.

Indicates whether the report shows subtotals, such as column or row totals.

API name of the field on which the report is sorted and the direction of the sort (asc or desc).

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.

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.

Indicates whether the report type supports role hierarchy filtering

(true) or not (false).

Describes a row limit filter applied to the report.

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

chartType groupings hasLegend showChartValues summaries

Type

String

String

Boolean

Boolean

Array of strings

Description

Type of chart.

Report grouping.

Indicates whether the report has a legend.

Indicates whether the report shows chart values.

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.

196

Report Types API Resource Reference

Property Type

sortAggregate

String

Report Type

Description

•

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.

Specifies the axis that shows the summary values. Valid values are

X

and

Y

.

Name of the chart.

summaryAxisLocations

String title

String

Groupings down

Property

name sortOrder

Type

String

String dateGranularity

String

Description

API name of the field used as a row grouping.

Order in which data is sorted within a row grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

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

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.

{

"aggregates": ["s!SALES","RowCount"],

"groupingsDown": [

197

Report Types API Resource Reference

Property Type Description

{

"name": "USERS.NAME",

"sortOrder": "Desc",

"dateGranularity": "None",

"sortAggregate": "s!SALES"

}

]

}

Report Type

Groupings across

Property

name sortOrder dateGranularity

Type

String

String

String

Description

API name of the field used as a column grouping.

Order in which data is sorted within a column grouping. Value can be:

•

Asc

for ascending order.

•

Desc

for descending order.

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

column isRunPageEditable operator

Type

String

Boolean

String

Description

Unique API name for the field that’s being filtered.

Indicates if this is an editable filter in the user interface.

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

198

Report Types API Resource Reference

Property

value

Type

String

Report Type

Description

•

notEqual

•

lessThan

•

greaterThan

•

lessOrEqual

•

greaterOrEqual

•

contains

•

notContain

•

startsWith

•

includes

•

excludes

•

within

(

DISTANCE

criteria only)

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

bucketType developerName label nullTreatedAsZero otherBucketLabel sourceColumnName values

Type

BucketType

String

String

Boolean

String

String

Array of

BucketTypeValues

Description

The type of bucket. Possible values are number

, percent

, and picklist

API name of the bucket.

User-facing name of the bucket.

Specifies whether null values are converted to zero ( true

) or not

( false

).

Name of the fields grouped as “Other” (in buckets of

BucketType

PICKLIST

).

Name of the bucketed field.

Describes the values included in the bucket field..

199

Report Types API Resource Reference Report Type

Bucket field value

Property

label sourceDimensionValues

Type

String

String rangeUpperBound

Custom summary formula

Property

label description formulaType decimalPlaces downGroup downGroupType acrossGroup

Double

Type

String

String

String

Integer

String

String

String

Description

The user-facing name of the bucket.

A list of the values from the source field included in this bucket category (in buckets of type

PICKLIST

and buckets of type

TEXT

).

The greatest range limit under which values are included in this bucket category (in buckets of type

NUMBER

).

Cross filter

Property

criteria includesObject primaryEntityField relatedEntity relatedEntityJoinField

Type Description

Array of

Filter details[]

Information about how to filter the relatedEntity

. Use to relate the primary entity with a subset of the relatedEntity

.

Boolean Specifies whether objects returned have a relationship with the relatedEntity

(true) or not ( false

).

String

String

String

The name of the object on which the cross filter is evaluated.

The name of the object that the primaryEntityField

is evaluated against. (The right-hand side of the cross filter).

The name of the field used to join the primaryEntityField and relatedEntity

.

Description

The user-facing name of the custom summary formula.

The user-facing description of the custom summary formula.

The format of the numbers in the custom summary formula. Possible values are number

, currency

, and percent

.

The number of decimal places to include in numbers.

The name of a row grouping when the downGroupType

is

CUSTOM

.

Null

otherwise.

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The name of a column grouping when the is

CUSTOM

.

Null

otherwise.

accrossGroupType

200

Report Types API Resource Reference Report Type

Property

acrossGroupType formula

Type

String

String

Description

Where to display the aggregate of the custom summary formula.

Possible values are all

, custom

, and grand_total

.

The operations performed on values in the custom summary formula.

Top rows

Property

rowLimit direction

Type

Integer

String

Description

The number of rows returned in the report.

The sort order of the report rows.

Report type metadata

Property

categories dataTypeFilterOperatorMap

Type

Categories[]

Filter operator reference

Description

All fields in the report type organized by section.

Lists all the possible field data types that can be used to filter the report. Each data type, such as phone, percent, currency, or picklist has two properties: name

: Of type string, this is a unique API name for each field type’s filter criteria. Use this API name in the metadata to define filter criteria for a report.

label

: Of type string, this is the display name for each filter criteria available to fields of a particular data type. For example, multipicklist

fields can have for filter criteria, “equals,”

“not equal to,” “includes,” and “excludes.” Bucket fields are considered to be of string

data type.

divisionInfo scopeInfo

Division info[]

Scope info[]

Default division and list of all possible record-level divisions that can be used in a report.

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.

standardDateFilterDurationGroups

Standard date filter duration groups[]

List of standard date filters available in reports.

standardFilterInfos

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.

201

Report Types API Resource Reference

Categories

Property

label

Type

String columns

Report Type

Column map

Description

Display name of a section in the report type under which fields are organized. For example, in an Accounts with Contacts custom report type,

Account General

is the display name of the section that has fields on general account information.

Information for all fields in the report type organized under a particular section’s unique API name.

Division info

Property

defaultValue values

Type

String

String

Description

Users are assigned a default division that applies to their newly created accounts, leads, and custom objects that are enabled for divisions.

All division values. Division values have two properties: label

: Display name of a division.

name

: Unique API name of a division.

Column map

Property

label filterValues

Type

String

String array dataType filterable

String

Boolean

Description

Display name of a field.

All filter values for a field, if the field data type is of picklist, multi-select picklist, boolean, or checkbox. For example, checkbox fields always have a value of

True

or

False

. For fields of other data types, the filter value is an empty array because their values can’t be determined. Filter values have two properties: name

: Unique API name for a filter value. Of type string.

label

: Display name of a filter value. Of type string.

Data type of the field.

False

means that the field is of a type that can’t be filtered. For example, fields of the type

Encrypted Text

can’t be filtered.

202

Report Types API Resource Reference

Scope Info

Property

defaultValue values

Report Type

Type

String

Array of strings

Description

Default scope of the data on which you run the report.

All scope values. Valid values depend on the report type. Scope values have the following properties: allowsDivision

: Allows you to segment the report by this scope.

label

: Display name of the scope.

value

: Value of the scope.

Standard date filter duration groups

Property

label

Type

String

Description

Display name of the standard date filter grouping. Valid values are Calendar Year, Calendar Quarter, Calendar Month, Calendar

Week, Fiscal Year, Fiscal Quarter, Day and custom value based on a user-defined date range.

standardDateFilterDurations

Standard date filter durations[]

Details about each possible relative date filter defined under the standard date filter grouping.

Standard date filter durations

Property

endDate label

Type

String

String startDate value

String

String

Description

End date of a date filter.

Display name of a date filter. Valid date filters are relative date filters—like

Current FY

and

Current FQ

—and custom date filters.

Start date of a date filter.

API name of a date filter. Valid date filters are relative date filters—like

THIS_FISCAL_YEAR

and

NEXT_FISCAL_QUARTER

—and custom date filters.

203

CHAPTER 7

Filter Operators API Resource Reference

In this chapter ...

•

Filter Operator List

Use the Filter Operators API to get information about which filter operators are available for reports and dashboards. The Filter Operators API is available in API version 40.0 and later.

Resources for the Filter Operators API are available at

/services/data/

<latest API

version>/analytics/filteroperators

. You can query each resource with an

HTTP method.

Resource

/services/data/

<latest API

version>/analytics/filteroperators and

/services/data/

<latest API

version>/analytics/filteroperators?forDashboards=true

GET

Supported

HTTP

Method

Description

Returns a list of filter operators available for report filters. When forDashboards

is true

, returns a list of filter operators available for dashboard filters.

204

Filter Operators API Resource Reference

Filter Operator List

Return a list of filter operators.

Syntax

URI

/vXX.X/analytics/reportTypes

Formats

JSON

HTTP methods

Method

GET

Description

Returns a list of filter operators.

Filter Operator List

Parameters

Parameter Description

forDashboards

Optional. When forDashboards

equals true

, returns filter operators for dashboard filters. Otherwise, the

GET response always returns filter operators for report filters.

GET Response Body

Returns an array of field data types. Each object contains the following fields:

Property

label name

Type

String

String

Description

The end user-facing name of the operator.

The API name of the operator.

Example GET Reponse Body

{

"date" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

205

Filter Operators API Resource Reference

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"string" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"double" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

206

Filter Operator List

Filter Operators API Resource Reference

} ],

"picklist" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"textarea" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

207

Filter Operator List

Filter Operators API Resource Reference

"label" : "starts with",

"name" : "startsWith"

} ],

"percent" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"url" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"int" : [ {

"label" : "equals",

"name" : "equals"

}, {

208

Filter Operator List

Filter Operators API Resource Reference

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"reference" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

} ],

"datetime" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"boolean" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

} ],

"phone" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

209

Filter Operator List

Filter Operators API Resource Reference

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"currency" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

} ],

"id" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"email" : [ {

"label" : "equals",

"name" : "equals"

210

Filter Operator List

Filter Operators API Resource Reference

}

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "less than",

"name" : "lessThan"

}, {

"label" : "greater than",

"name" : "greaterThan"

}, {

"label" : "less or equal",

"name" : "lessOrEqual"

}, {

"label" : "greater or equal",

"name" : "greaterOrEqual"

}, {

"label" : "contains",

"name" : "contains"

}, {

"label" : "does not contain",

"name" : "notContain"

}, {

"label" : "starts with",

"name" : "startsWith"

} ],

"multipicklist" : [ {

"label" : "equals",

"name" : "equals"

}, {

"label" : "not equal to",

"name" : "notEqual"

}, {

"label" : "includes",

"name" : "includes"

}, {

"label" : "excludes",

"name" : "excludes"

} ]

Filter Operator List

211

CHAPTER 8

Dashboards API Resource Reference

In this chapter ...

•

Dashboard List

•

Dashboard Results

•

Dashboard Describe

•

Dashboard Status

•

Dashboard Filter

Options Analysis

•

Dashboard and

Component Error

Codes

The Dashboards API provides several resources for accessing and refreshing dashboards.

Resources for the Dashboards API are available at

/services/data/

<latest API

version>/analytics/dashboards

. You can query each resource with an HTTP method (such as GET). Use these resources to integrate dashboard data directly into your applications.

Resource Supported

HTTP

Method

Description

Dashboard List

GET

POST

Dashboard Results

GET

POST

PUT

PATCH

DELETE

Returns a list of recently used dashboards.

Makes a copy of a dashboard.

Returns the metadata, data, and status for the specified dashboard.

Returns details about specified dashboard components.

Triggers a dashboard refresh.

Saves a dashboard.

Deletes a dashboard.

Dashboard Status

GET

Dashboard

Describe

Dashboard Filter

Options Analysis

GET

POST

Returns the status for the specified dashboard.

Returns metadata for the specified dashboard, including dashboard components, filters, layout, and the running user.

Verifies that dashboard filter options are compatible with report fields. Specify the reportId

of a dashboard’s components’ source report.

212

Dashboards API Resource Reference

Dashboard List

Returns a list of recently used dashboards or clones a dashboard.

Syntax

URI

/vXX.X/analytics/dashboards

Formats

JSON

HTTP methods

Method

GET

POST

Description

Returns a list of dashboards that were recently viewed by the API user. See this

example .

Makes a copy of a dashboard. See this example

.

Authentication

Authorization: Bearer

token

GET Response body

An array of recent dashboard objects. Each object contains the following fields:

Property

id name statusUrl url

Type

String

String

String

String

Description

Unique identifier of the dashboard.

Localized display name of the dashboard.

Dashboard status URL.

Dashboard result URL.

POST Response Body

Uses the same format as the GET and PUT responses

for the Dashboard Results resource.

Dashboard Results

Can return metadata, data, and status for the specified dashboard. Can also refresh, save, or delete a dashboard.

Syntax

URI

/vXX.X/analytics/dashboards/

dashboardID

213

Dashboard List

Dashboards API Resource Reference Dashboard Results

Or, with optional parameters:

/vXX.X/analytics/dashboards/

dashboardID

?runningUser= runningUserID&filter1=filter1ID&filter2=filter2ID&filter3=filter3ID

Formats

JSON

HTTP methods

Method

GET

POST

PUT

PATCH

DELETE

Description

Returns metadata, data, and status for the specified dashboard. See this example

.

Returns details about one or more dashboard components from a specified dashboard. See this

example .

Triggers a dashboard refresh. See this example

.

Saves a dashboard. See this example

.

Deletes a dashboard. See this

example .

Authentication

Authorization: Bearer

token

Parameters

The following optional parameters can be used with the GET and PUT methods:

Parameter Name

runningUser filter1 filter2 filter3 isStickyFilterSave

Description

Identifier of the running user. Gives an error if the user is not allowed to change the running user, or if the selected running user is invalid.

Identifier of the selected filter option for the first filter. Gives an error if the filter option is invalid.

Identifier of the selected filter option for the second filter. Gives an error if the filter option is invalid.

Identifier of the selected filter option for the third filter. Gives an error if the filter option is invalid.

Append to a PATCH request. When true

, saves any dashboard filters set in the request so that they’re also set the next time you open the dashboard. You can only set dashboard filters for yourself, not for other users.

GET, POST, and PUT Response body

Property

componentData

Type

Component data

[] dashboardMetadata

Dashboard metadata

Description

Ordered array containing data and status for each component of the dashboard.

Metadata for the entire dashboard.

214

Dashboards API Resource Reference Dashboard Results

Attributes

Property

dashboardId dashboardName statusUrl type

Type

String

String

Url

String

Component data

Property

componentId reportResult status

Type

String

Report results

Component status

Description

Unique identifier of dashboard.

Dashboard name.

The URL of the status resource for the dashboard.

This property is always set to

Dashboard

.

Description

Unique identifier of the component.

Report metadata and summary data for the dashboard component. Uses the same data format as the Report API.

Queue and data status of the component.

Component status

Property

dataStatus errorCode errorMessage errorSeverity

Type

String

String

String

String refreshDate refreshStatus

Date and time string

String

Description

Status of the data set of the component. Value can be:

•

NODATA

: The data set was never generated or is invalid due to a change in the report.

•

DATA

: The data set is available and was last refreshed at the refreshDate

.

•

ERROR

: A component error has occurred. Details can be found in errorCode

, errorMessage

, and errorSeverity

.

Unique identifier of error message. This property is only populated in case of error.

Localized error message. This property is only populated in case of error.

Severity of error code and message. Value can be:

•

Error

•

Warning

This property is only populated in case of error.

Date and time of last refresh in ISO-8601 format.

Refresh status of the component. Value can be:

•

IDLE

: The component is not currently being refreshed.

•

RUNNING

: The component is currently being refreshed.

215

Dashboards API Resource Reference

Dashboard metadata

Property

attributes canUseStickyFilter developerName filters

Type

Attributes

canChangeRunningUser

Boolean

Boolean components description dashboardType

Components

[]

String

String

String

Filters

[] folderId id layout maxFilterOptions name runningUser

String

String

Layout

Integer

String

Running user

Dashboard Results

Description

Attributes for the dashboard resource, such as name, identifier, and references to other related resources.

Indicates whether the user is allowed to select a specific running user.

Always true

for team dashboards.

Indicates whether dashboard filters persist after closing the dashboard

( true

) or not ( false

). Filters that persist keep the dashboard filtered the next time you open it. Filters persist for users on a per-user basis, so if you apply a filter then it doesn’t persist for other people.

Ordered array of components in this dashboard.

Dashboard description.

Indicates whether a dashboard is a dynamic dashboard, a dashboard with running users, or a standard dashboard. Possible values are:

•

SpecifiedUser

— Dashboard readers view data as though they are the person specified by runningUser

•

LoggedInUser

— Dashboard readers view data as themselves.

The dashboard is a dynamic dashboard.

•

MyTeamUser

— Dashboard readers view data as the person specified by runningUser

by default. If they have the “View All

Data” user permission then they can change the runningUser

to anyone. If they have the “View My Team’s Dashboards” user permission then they can change the runningUser

to people subordinate to them in the role hierarchy.

Unique API name of the dashboard.

Ordered array of filters for this dashboard. The dashboard can have 0-3 filters.

ID of the folder that contains the dashboard.

Unique identifier of dashboard.

Component layout for this dashboard.

The maximum number of values allowed in a dashboard filter.

Dashboard name.

The running user, which is either specified at dashboard design time, or is overridden by the runningUser

parameter specified in the GET request. For dynamic dashboards, this is always the current user.

216

Dashboards API Resource Reference Dashboard Results

Components

Property

componentData footer header id properties reportId title type

Type

Integer

String

String

String

Properties (for Report component type)

Properties (for

Visualforce page component type)

String

String

String

Description

Index into the component data array in the response body.

Footer of the component.

Header of the component.

Unique identifier of the component.

Component properties, including type-specific visualization properties.

Unique identifier of the underlying report.

Title of the component

Type of the component. Value can be:

•

Report

•

VisualforcePage

If the component is an SControl, the value is not set.

Filters

Property

errorMessage

Type

String name options selectedOption

String

Filter option

Integer

Description

If there is no error with a dashboard filter, then null

. Otherwise, the error message is returned.

Localized display name of filter.

Ordered array of possible filter options.

Index of the selected option from the options

array. This matches the selection that was made based on the filter1

, filter2

, or filter3

parameter. Value is null

if no option is selected.

Filter option

Property

alias id

Type

String

String

Description

Optional alias of the filter option.

Unique identifier of the filter option. Used as a value for the filter2

, and filter3

parameters.

filter1

,

217

Dashboards API Resource Reference

Property

operation

Type

String

Dashboard Results

Description

Unique API name for the filter operation. Valid filter operations depend on the data type of the filter field. Value can be:

•

equals

•

notEqual

•

lessThan

•

greaterThan

•

lessOrEqual

•

greaterOrEqual

•

contains

•

notContain

•

startsWith

•

includes

•

excludes

•

within

•

between

Value to filter on. Used for all operations except between

.

Start value when using a between

operation. Not set for all other operations.

End value when using a between

operation. Not set for all other operations.

value startValue endValue

String

String

String

Layout

Property

columns

Type

Columns

[] components

Components

Columns

Property

components

Type

Integer[]

Description

Dashboard layout columns. Can have 2 or 3 columns, including empty columns. This property is available only if the dashboard was created using

Salesforce Classic.

Layout for dashboards. This property is available only if the dashboard was created using Lightning Experience.

Description

Ordered list of components in a column (top to bottom). Components are represented by indices into the array of components in the dashboard metadata object.

218

Dashboards API Resource Reference Dashboard Results

Components

Property

colspan rowspan column row

Type

Integer

Integer

String

String

Description

Width of component in columns. For example, if colspan=3

, then the component spans 3 columns.

Height of component in rows. For example, if rowspan=4

, then the component spans 4 rows.

Column position on the grid.

Row position on the grid.

Running user

Property

displayName id

Type

String

String

Description

Display name of running user.

Returns the ID of the running user specified for the dashboard. If the dashboard is configured to run as the viewing user, returns the user ID of the dashboard creator.

picklistColors

Property

color

Type

String

Properties (for Report component type)

Property

aggregates

Type

Array of strings

Description

The color in hexadecimal format used to represent a picklist value.

autoSelectColumns groupings

Boolean

String

Description

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.

Indicates whether groupings and aggregates are automatically selected.

Valid values are true

and false

.

Report groupings included in the dashboard.

219

Dashboards API Resource Reference Dashboard Results

Property

maxRows reportFormat sort

Type

Number

String

Sort

Description

Maximum number of rows to be rendered, based on the sort value.

The format of a dashboard’s source report.

Sorting information for the component.

useReportChart

Boolean Indicates whether the dashboard component uses the chart as defined in the report. Valid values are true

and false

.

visualizationProperties

Visualization properties

(Chart)

Type-specific visualization properties.

Visualization properties

(Table)

Visualization properties

(FlexTable)

Visualization properties

(Metric)

Visualization properties

(Gauge)

visualizationType

String Type of the component. Value can be:

•

Bar

•

Column

•

Donut

•

Funnel

•

Gauge

•

Line

•

Metric

•

Pie

•

Scatter

•

Table

•

FlexTable

(As of API Version 41.0. Beta in API Version 41.0)

Sort

Property

column sortOrder

Type

String

String

Description

Developer name for a sorted column.

Sort order. Value can be:

•

asc

•

desc

220

Dashboards API Resource Reference Dashboard Results

Visualization properties (Chart)

Property

axisRange groupByType legendPosition

Type

String

String

String showValues

Boolean

Description

Range of values specified for the axis.

Type of second-level grouping.

Position of legend on the grid. Valid values are bottom

, right

, and none

.

Indicates whether to include values in the chart. Valid values are true and false

.

Visualization properties (Table)

Property

breakPoints tableColumns

Type

Break point

[]

Table columns

[]

Description

Break points for the table component.

Columns of the table component.

Visualization properties (FlexTable)

FlexTable is the API name of the Lightning dashboard table. Lightning dashboard table is beta in API version 41.0.

Property

tableColumns

Type

Table columns

[]

Description

Columns of the table component.

Visualization properties (Metric)

Property

breakPoints metricLabel

Type

Break point

[]

String

Visualization properties (Gauge)

Property

breakPoints displayUnits

Type

Break point

[]

String

Description

Break points for the metric component.

Label for the metric component.

Description

Break points for the gauge component.

Specify how to display numbers. Possible values are:

•

whole

— Display the true value of the number without rounding it.

•

auto

— Display the number rounded to the nearest thousand, million, etc. and displayed as a shortened value. For example, 1,876 displays as 1.9k. In calculating summaries, the true value of the number

(1,876) is used , even if 1.9k is displayed.

221

Dashboards API Resource Reference

Property Type

showPercentages

Boolean showTotal

Boolean

Break point

Property

aggregateName

Type

String breaks

Break

[]

Break

Property

color

Type

String lowerBound upperBound

Number

Number

Table columns

Property

column isPercent

Type

String

Boolean scale showTotal type

Number

Boolean

String

Dashboard Results

Description

•

null

— Customizing how numbers display isn’t applicable..

Specify whether percentages are displayed ( true

) or not ( false

)

Indicates whether the total is displayed ( true

) or not ( false

).

Description

Aggregate column developer name that the break points have been applied to.

Break values for a break point.

Description

A hex value representing the color for the break point.

Note:

Description

Developer name for the aggregate or grouping column.

Indicates whether the column value is shown as a percent ( true

) or not ( false

).

Not supported for

Type of the column. Valid values are:

•

detail

•

aggregate

222

FlexTables

.

The number of decimal places for the column value.

Not supported for

FlexTables

.

Indicates whether the column shows the total ( true

) or not

( false

).

A color value of black displays only 1 character (0) instead of 6 characters (000000).

Lower bound for the break point.

Upper bound for the break point.

Dashboards API Resource Reference

Property Type Description

•

grouping

Properties (for Visualforce page component type)

Property

pageName height

Type

String

String

Description

Developer name of the Visualforce page.

Height of the Visualforce page, in pixels.

tableChatterPhotoUrls

Property

chatterPhotoUrl

Type

String

Description

URL pointing to a user's Chatter photo.

PUT Response body

Property

statusUrl

Type

String

POST Request body

Property

componentIds

Type

Array of Strings

Description

URL of the status resource for the dashboard.

Description

Dashboard component ids.

Dashboard Describe

Returns metadata for the specified dashboard, including dashboard components, filters, layout, and the running user.

Syntax

URI

/vXX.X/analytics/dashboards/ dashboardID/describe

Formats

JSON

HTTP methods

GET

Dashboard Describe

223

Dashboards API Resource Reference Dashboard Describe

Parameters

Parameter Description

loadComponentProperties

Optional. Specifies whether or not to return properties for each dashboard component. The default value is true

.

Has no effect on filtered dashboards. Valid values are:

•

true

— Return component properties.

•

false

— Don’t return component properties. The properties

value instead returns null

.

Authentication

Authorization: Bearer

token

Example

See this example, Get Dashboard Metadata .

Response body

Property

components filters layout runningUser

Type

Component

[]

Filter

[]

Layout

Running user

Description

Ordered array of components in this dashboard.

Ordered array of filters for this dashboard. The dashboard can have 0 to 3 filters.

Component layout for this dashboard

The running user, which is either specified at dashboard design time or is overriden by the runningUser

parameter. For dynamic dashboards, this is always the current user.

Components

Property

componentData footer header id properties reportId

Type

Integer

String

String

Description

Index into the component data array in the response body.

Footer of the component.

Header of the component.

String Unique identifier of the component.

Properties (for Report component type)

Properties (for Visualforce page component type)

Component properties, including type-specific visualization properties.

String Unique identifier of the underlying report.

224

Dashboards API Resource Reference Dashboard Describe

Property

title type

Type

String

String

Description

Title of the component

Type of the component. Value can be:

•

Report

•

VisualforcePage

If the component is an SControl, the value is not set.

Properties (for Report component type)

Property

aggregates

Type

Array of strings

Description

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.

autoSelectColumns groupings maxRows reportFormat sort

Boolean

String

Number

String

Sort

Indicates whether groupings and aggregates are automatically selected.

Valid values are true

and false

.

Report groupings included in the dashboard.

Maximum number of rows to be rendered, based on the sort value.

The format of a dashboard’s source report.

Sorting information for the component.

useReportChart

Boolean Indicates whether the dashboard component uses the chart as defined in the report. Valid values are true

and false

.

visualizationProperties

Visualization properties

(Chart)

Type-specific visualization properties.

Visualization properties

(Table)

Visualization properties

(FlexTable)

Visualization properties

(Metric)

225

Dashboards API Resource Reference Dashboard Describe

Property

visualizationType

Type

Visualization properties

(Gauge)

Description

String Type of the component. Value can be:

•

Bar

•

Column

•

Donut

•

Funnel

•

Gauge

•

Line

•

Metric

•

Pie

•

Scatter

•

Table

•

FlexTable

(As of API Version 41.0. Beta in API Version 41.0)

Sort

Property

column sortOrder

Type

String

String

Description

Developer name for a sorted column.

Sort order. Value can be:

•

asc

•

desc

Visualization properties (Chart)

Property

axisRange groupByType

Type

String

String legendPosition

String showValues

Boolean

Description

Range of values specified for the axis.

Type of second-level grouping.

Position of legend on the grid. Valid values are bottom

, right

, and none

.

Indicates whether to include values in the chart. Valid values are true and false

.

226

Dashboards API Resource Reference Dashboard Describe

Visualization properties (Table)

Property

breakPoints tableColumns

Type

Break point

[]

Table columns

[]

Visualization properties (Metric)

Property

breakPoints metricLabel

Type

Break point

[]

String

Description

Break points for the table component.

Columns of the table component.

Description

Break points for the metric component.

Label for the metric component.

Visualization properties (Gauge)

Property

breakPoints displayUnits

Type

Break point

[]

String showPercentages

Boolean showTotal

Boolean

Description

Break points for the gauge component.

Specify how to display numbers. Possible values are:

•

whole

— Display the true value of the number without rounding it.

•

auto

— Display the number rounded to the nearest thousand, million, etc. and displayed as a shortened value. For example, 1,876 displays as 1.9k. In calculating summaries, the true value of the number (1,876) is used , even if 1.9k is displayed.

•

null

— Customizing how numbers display isn’t applicable..

Specify whether percentages are displayed ( true

) or not ( false

)

Indicates whether the total is displayed ( true

) or not ( false

).

Properties (for Visualforce page component type)

Property

pageName height

Type

String

String

Description

Developer name of the Visualforce page.

Height of the Visualforce page, in pixels.

227

Dashboards API Resource Reference

Filters

Property

errorMessage

Type

String name options selectedOption

String

Filter option

Integer

Dashboard Describe

Description

If there is no error with a dashboard filter, then null

. Otherwise, the error message is returned.

Localized display name of filter.

Ordered array of possible filter options.

Index of the selected option from the options

array. This matches the selection that was made based on the filter1

, filter2

, or filter3 parameter. Value is null

if no option is selected.

Filter option

Property

alias id operation

Type

String

String

String value startValue endValue

String

String

String

Description

Optional alias of the filter option.

Unique identifier of the filter option. Used as a value for the filter1

, filter2

, and filter3

parameters.

Unique API name for the filter operation. Valid filter operations depend on the data type of the filter field. Value can be:

•

equals

•

notEqual

•

lessThan

•

greaterThan

•

lessOrEqual

•

greaterOrEqual

•

contains

•

notContain

•

startsWith

•

includes

•

excludes

•

within

•

between

Value to filter on. Used for all operations except between

.

Start value when using a between

operation. Not set for all other operations.

End value when using a between

operation. Not set for all other operations.

228

Dashboards API Resource Reference

Layout

Property

columns

Type

Columns []

components

Components

Columns

Property

components

Type

Integer[]

Description

Dashboard layout columns. Can have 2 or 3 columns, including empty columns. This property is available only if the dashboard was created using

Salesforce Classic.

Layout for dashboards. This property is available only if the dashboard was created using Lightning Experience.

Description

Dashboard Status

Ordered list of components in a column (top to bottom). Components are represented by indices into the array of components in the dashboard metadata object.

Components

Property

colspan rowspan column row

Running user

Property

displayName id

Type

String

String

Type

Integer

Integer

String

String

Description

Width of component in columns. For example, if colspan=3

, then the component spans 3 columns.

Height of component in rows. For example, if rowspan=4

, then the component spans 4 rows.

Column position on the grid.

Row position on the grid.

Description

Display name of running user.

Returns the ID of the running user specified for the dashboard. If the dashboard is configured to run as the viewing user, returns the user ID of the dashboard creator.

Dashboard Status

Returns the status for the specified dashboard.

229

Dashboards API Resource Reference Dashboard Status

Syntax

URI

/vXX.X/analytics/dashboards/ dashboardID/status

Or, with optional parameters:

/vXX.X/analytics/dashboards/ dashboardID/status

?runningUser= runningUserID&filter1=filter1ID&filter2=filter2ID&filter3=filter3ID

Formats

JSON

HTTP methods

GET

Authentication

Authorization: Bearer

token

Parameters

The following optional parameters can be used with the GET method:

Parameter Name

runningUser filter1 filter2 filter3

Description

ID of the running user. Gives an error if the user is not allowed to change the running user, or if the selected running user is invalid.

ID of the selected filter option for the first filter. Gives an error if the filter option is invalid.

ID of the selected filter option for the second filter. Gives an error if the filter option is invalid.

ID of the selected filter option for the third filter. Gives an error if the filter option is invalid.

Response body

Property

componentStatus

Type

Component status with id

[]

Description

Status for each component of the dashboard. The order of the array is the same as in previous calls, unless the dashboard has changed in the meantime.

Component status with id

Property

componentId refreshDate refreshStatus

Type

String

Date and time string

String

Description

Unique ID of the dashboard component.

Date and time of last refresh in ISO-8601 format.

Refresh status of the component. Value can be:

•

IDLE

: The component is not currently being refreshed.

•

RUNNING

: The component is currently being refreshed.

230

Dashboards API Resource Reference Dashboard Filter Options Analysis

Dashboard Filter Options Analysis

Verifies that dashboard filter options are compatible with source report fields. Use this resource to testAvailable in API version 40.0 and later.

Syntax

URI

/vXX.X/analytics/dashboards/

dashboardID/filteroptionsanalysis

Formats

JSON

HTTP methods

POST

Authentication

Authorization: Bearer

token

POST Request Body

Property

filterColumns

Type

filterColumns[] options options[]

Description

An array of fields from the source report which you check filter values against.

Each object in the array has these properties:

reportId

The the source report’s unique ID.

name

The report field’s API name.

An array of objects describing a dashboard filter. Each object has these properties:

alias

The display name of the filter value.

operation

The filter’s operator.

value

The value applied by the filter.

startValue

If the filter includes a range (such as a date range), the start of the range.

Otherwise, null.

endValue

If the filter includes a range (such as a date range), the end of the range.

Otherwise, null.

231

Dashboards API Resource Reference Dashboard and Component Error Codes

POST Response Body

If successful, returns an empty response.

Example POST Request

{

"filterColumns" : [{

"reportId": "00OR0000000P76tMAC",

"name": "ACCOUNT_TYPE"

}],

"options": [{

"alias": "New",

}

}]

"operation": "contains",

"value": "New",

"startValue": null,

"endValue": null

Dashboard and Component Error Codes

Errors can occur at the dashboard level and at the component level.

Dashboard-level error messages are returned in the response header, and component-level error messages are returned as part of the component status object.

Dashboard-level errors

When a dashboard-level error occurs, the response header contains an HTTP response code and one of the following error messages:

Error Message HTTP

Response

Code

400

400

400

400

400

400

The running user for this dashboard doesn't have permission to run reports. Your system administrator should select a different running user for this dashboard.

The running user for this dashboard is inactive. Your system administrator should select an active user for this dashboard.

You don't have permission to view data as this user.

Your organization has reached the limit for dynamic dashboards, or doesn't have access. Ask your administrator to enable dynamic dashboards or convert them to dashboards with a specific running user.

The selected filter item isn't valid.

You can't refresh this dashboard. A refresh is already in progress.

232

Dashboards API Resource Reference Dashboard and Component Error Codes

Component-level errors

If an error occurs at the component level, the errorCode

, errorMessage

, and errorSeverity

properties of the component status field are populated. The errorSeverity

property distinguishes between errors and warnings. Errors are blocking issues that prevent the query from returning any data. Warnings are non-blocking issues; queries will finish, but they might return incomplete data.

The following table shows the possible values for the error fields.

302

303

304

205

208

209

errorCode

201

202

203

210

211

212

300

301

305

308

309

errorMessage

This component must have a type and a data source.

errorSeverity

Error

The source report isn't available; it's been deleted or isn't in a folder accessible to the dashboard's running user.

Error

This report can no longer be edited or run. Your administrator has disabled all reports for the custom or external object, or its relationships have changed.

Error

The source report is based on a report type that is inaccessible to the dashboard's running user.

Error

Unable to run source report because its definition is invalid.

Error

This report cannot be used as the source for this component. If it is a summary or matrix report, add one or more groupings in the report. If it is a tabular report with a row limit, specify the

Dashboard Settings in the report.

Error

This row-limited tabular report cannot be used as the source for this component. Use the dashboard component editor to specify the data you want to display, or specify the Dashboard

Settings in the report.

Error

To use this row-limited tabular report as the source, edit the report and specify the Name and

Value under Dashboard Settings. When updating the report, make sure you are the running user of the dashboard.

Error

Groupings and combination charts are not available for a row-limited tabular report. Set “Group

By” to None and deselect “Plot Additional Values.”

Error

The results below may be incomplete because the underlying report produced too many summary rows, and the sort order of the component is different from the sort order in the underlying report. Try adding filters to the report to reduce the number of rows returned.

Error

Results may be incomplete because the source report had too many summary rows. Try filtering the report to reduce the number of rows returned.

Warning

The component can't be displayed because the source report exceeded the time limit.

Warning

The component can't be displayed because the source report failed to run.

The component can't be displayed because the dashboard filter raises the number of source report filters above the limit. Reduce the number of report filters and try again.

The component can't be displayed because the field(s) you chose for the filter are unavailable.

Error

Error

The underlying report uses a snapshot date that is out of range.

Error

You can’t filter this component because data is in the joined report format. To filter the component, change its report format.

Error

Error

233

CHAPTER 9

Analytics Notifications API Resource Reference

In this chapter ...

•

Analytics Notification

List

•

Analytics Notification

•

Analytics Notification

Limits

Use the Analytics Notifications API to work set up custom analytics notifications. The Analytics Notifications

API is available in API version 38.0 and later.

Resources for the Analytics Notifications API are available at

/services/data/

<latest API

version>/analytics/notifications

. You can query each resource with an

HTTP

method.

Resource Supported

HTTP

Method

Description

Analytics

Notification List

GET

/services/data/

<latest

API

version>/analytics/notifications

POST

Returns a list of recent notifications.

Create an analytics notification.

Analytics

Notification

GET

PUT

/services/data/

<latest

API

DELETE

version>/analytics/notifications/<Id>

Analytics

Notification Limits

GET

/services/data/

<latest

API v r o

/ a t s o i a n / i s

Returns information about a specific notification.

Save changes to the notification as specified in the request body.

Delete the notification. Deleted notifications can't be recovered.

Check to see how many more analytics notifications you can create.

234

Analytics Notifications API Resource Reference

Analytics Notification List

Return a list of analytics notifications (

GET

) or create an analytics notification (

POST

).

Syntax

URI

/vXX.X/analytics/notifications?source=waveNotification

Formats

JSON

HTTP methods

Method

GET

POST

Description

Returns a list of analytics notifications.

Create an analytics notification.

Parameters

Parameter Description

source

Required for

GET

calls. Specifies what type of analytics notification to return. Valid values are:

•

lightningReportSubscribe

— report subscriptions

•

waveNotification

— Wave notifications recordId

Optional. Return notifications for a single record. Valid values are:

•

reportId

— Unique report ID

•

lensId

— Unique Wave lens ID

Analytics Notification List

GET and POST Response Body

An array of notification objects. Each object contains the following fields:

Property

active configuration

Type

Boolean

WaveConfiguration[]

createdDate

DateTime deactivateOnTrigger

Boolean

Description

Indicates whether the notification is being sent ( true

) or not ( false

).

Describes details of a Wave notification. Only applicable when source

is waveNotification

.

Date and time when the notification was created (in ISO 8601 format).

Indicates whether the notification is deactivated after it's sent ( true

) or not

( false

). Deactivation doesn't delete the notification.

The default value is false

.

235

Analytics Notifications API Resource Reference

Property

id

Type

String lastModifiedDate

DateTime name recordId

String

String runAs schedule source

runAs

Schedule

String

Analytics Notification List

Description

Unique notification ID.

Date and time when the notification was last modified (in ISO 8601 format).

Display name of the notification.

Unique ID of the record that the notification describes. Valid values are:

•

reportId

•

lensId

The person who runs the report in a report subscription. Report recipients see data in the emailed report that this person has access to in Salesforce.

Available in API version 40.0 and later. Only appears if you have the “Subscribe to Reports: Add Recipients” user perm.

Details about the notification's schedule.

Indicates the type of notification. Possible values are:

•

lightningSubscribe

— report subscriptions

•

waveNotification

— Wave notifications

Specifies what happens when the notification runs. For example, sending an email with report results.

thresholds

Threshold[]

runAs

Property

id name

Schedule

Property

frequency

Type

String

String

Type

String

Description

The person’s unique Salesforce user ID.

The person’s first and last name.

frequencyType

String

Description

How frequently the notification is invoked. Possible values are:

•

daily

— Every day

•

weekly

— One or more days each week

•

monthly

— One or more days each month

Only necessary when frequency

is monthly

. Possible values are:

•

relative

— Days which can change month-to-month, as described by details

.

•

specific

— Fixed monthly dates, as described by details

.

236

Analytics Notifications API Resource Reference

Property

details

Type

ScheduleDetail[]

Analytics Notification List

Description

Describes the notification schedule. Varies depending on whether frequency

is daily

, weekly

, or monthly

.

ScheduleDetail ( frequency

is daily

)

Property

time

Type

Integer

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

ScheduleDetail ( frequency

is weekly

)

Property

time daysOfWeek

Type

Integer

String[]

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

The days of the week on which the notification is invoked. Possible values are:

•

mon

— Monday

•

tue

— Tuesday

•

wed

— Wednesday

•

thu

— Thursday

•

fri

— Friday

•

sat

— Saturday

•

sun

— Sunday

ScheduleDetail ( frequency

is monthly

, frequencyType

is relative

)

Property

time weekInMonth

Type

Integer

String

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

The week in the month during which the notification is invoked. Possible values are:

•

first

— First week

•

second

— Second week

•

third

— Third week

•

fourth

— Fourth week

237

Analytics Notifications API Resource Reference

Property

dayInWeek

Type

String

Analytics Notification List

Description

The day of the week on which the notification is invoked. Possible values are:

•

mon

— Monday

•

tue

— Tuesday

•

wed

— Wednesday

•

thu

— Thursday

•

fri

— Friday

•

sat

— Saturday

•

sun

— Sunday

•

weekday

— Weekday

•

weekend

— Weekend day

ScheduleDetail ( frequency

is monthly

, frequencyType

is specific

)

Property

time daysOfMonth

Type

Integer

Integer[]

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

The days of the month on which the notification is invoked. Possible values are integers from 1 to 31, and -1 (which represents the last day of the month).

Threshold

Property

type

Type

String conditions actions

Condition[]

Action[]

Description

Specifies when the notification is invoked (other than date and time criteria).

Possible values are:

•

always

— Always invoke the notification

•

onError

— Invoke the notification when there is an error

•

condition

— Invoke the notification based on criteria described by conditions

Describes conditions that govern when the notification is invoked.

Specifies what action is taken when the notification is invoked.

Condition

Property

colName

Type

String

Description

The data field which is operated on.

238

Analytics Notifications API Resource Reference

Property

value operation

Type

String

String

Analytics Notification List

Description

The comparison value which is used by the operation.

The operation which is used to evaluate the condition. Possible values are:

•

equal

— colName

and value

are equal

•

notEqual

— colName

and value

are not equal

•

greaterThan

— colName

is greater than value

•

lessThan

— colName

is less than value

•

greaterThanEqual

— colName

is greater than or equal to value

•

lessThanEqual

— colName

is less than or equal to value

Action

Property

type

Type

String

Description

The type of action to perform when the notification is invoked. Possible values are:

•

sendEmail

— Send an email to recipients

Specifies important attributes for resources related to the notification.

configuration

Configuration

Configuration

Property

recipients

Type

Recipient[]

Recipient

Property

id displayName

Type

String

String

WaveConfiguration

Property

anchor filter

Type

String

String

Description

A list of users, roles, and groups who receive the notification.

Description

Specifies who receives the notification. Valid values are the unique id of a user, role, or group.

The displayName

of the user, role, or group.

Description

Optional. The Id of the Wave dashboard widget to which the notification is anchored.

Optional. Description of selected filters at the time of notification creation.

239

Analytics Notifications API Resource Reference Analytics Notification

Property

query datasets

WaveDataset

Property

id name namespace

Type

String

WaveDataset[]

Type

String

String

String

Description

Required. SAQL query which is run when the notification is invoked.

Required. Collection of Wave datasets referenced by the notification.

Description

Required. Id of the Wave dataset.

Optional. Developer name of the Wave dataset.

Optional. Namespace of the Wave dataset.

POST Request Body

Uses the same format as the GET and POST response body.

Analytics Notification

Get information about (

GET

), save changes to (

PUT

) or delete (

DELETE

) a specific analytics notification.

Syntax

URI

/vXX.X/analytics/notifications/

analytics notification ID

Formats

JSON

HTTP methods

Method

GET

PUT

DELETE

Description

Returns information about a specific notification.

Save changes to the analytics notification as specified in the request body.

Delete the analytics notification. Deleted notifications can't be recovered.

Parameters

Parameter Description

source

Required for

GET

calls. Specifies what kind of analytic notification to return. Valid values are:

•

lightningReportSubscribe

— report subscriptions

•

waveNotification

— Wave notifications

240

Analytics Notifications API Resource Reference

Parameter Description

recordId

Optional. Return notifications for a single record. Valid values are:

•

reportId

— Unique report ID

•

lensId

— Unique Wave lens ID

Analytics Notification

GET Response Body

Property

active configuration

Type

Boolean

WaveConfiguration[]

createdDate

DateTime deactivateOnTrigger

Boolean id

String lastModifiedDate

DateTime name recordId

String

String runAs schedule source thresholds

runAs

Schedule

String

Threshold[]

Description

Indicates whether the notification is being sent ( true

) or not ( false

).

Describes details of a Wave notification. Only applicable when source

is waveNotification

.

Date and time when the notification was created (in ISO 8601 format).

Indicates whether the notification is deactivated after it's sent ( true

) or not

( false

). Deactivation doesn't delete the notification.

The default value is false

.

Unique notification ID.

Date and time when the notification was last modified (in ISO 8601 format).

Display name of the notification.

Unique ID of the record that the notification describes. Valid values are:

•

reportId

•

lensId

The person who runs the report in a report subscription. Report recipients see data in the emailed report that this person has access to in Salesforce.

Available in API version 40.0 and later. Only appears if you have the “Subscribe to Reports: Add Recipients” user perm.

Details about the notification's schedule.

Indicates the type of notification. Possible values are:

•

lightningSubscribe

— report subscriptions

•

waveNotification

— Wave notifications

Specifies what happens when the notification runs. For example, sending an email with report results.

241

Analytics Notifications API Resource Reference

runAs

Property

id name

Schedule

Property

frequency

Type

String

String

Type

String

Description

The person’s unique Salesforce user ID.

The person’s first and last name.

Analytics Notification frequencyType details

String

ScheduleDetail[]

Description

How frequently the notification is invoked. Possible values are:

•

daily

— Every day

•

weekly

— One or more days each week

•

monthly

— One or more days each month

Only necessary when frequency

is monthly

. Possible values are:

•

relative

— Days which can change month-to-month, as described by details

.

•

specific

— Fixed monthly dates, as described by details

.

Describes the notification schedule. Varies depending on whether frequency

is daily

, weekly

, or monthly

.

ScheduleDetail ( frequency

is daily

)

Property

time

Type

Integer

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

ScheduleDetail ( frequency

is weekly

)

Property

time

Type

Integer daysOfWeek

String[]

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

The days of the week on which the notification is invoked. Possible values are:

•

mon

— Monday

•

tue

— Tuesday

•

wed

— Wednesday

•

thu

— Thursday

•

fri

— Friday

242

Analytics Notifications API Resource Reference

Property Type

Analytics Notification

Description

•

sat

— Saturday

•

sun

— Sunday

ScheduleDetail ( frequency

is monthly

, frequencyType

is relative

)

Property

time weekInMonth dayInWeek

Type

Integer

String

String

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

The week in the month during which the notification is invoked. Possible values are:

•

first

— First week

•

second

— Second week

•

third

— Third week

•

fourth

— Fourth week

The day of the week on which the notification is invoked. Possible values are:

•

mon

— Monday

•

tue

— Tuesday

•

wed

— Wednesday

•

thu

— Thursday

•

fri

— Friday

•

sat

— Saturday

•

sun

— Sunday

•

weekday

— Weekday

•

weekend

— Weekend day

ScheduleDetail ( frequency

is monthly

, frequencyType

is specific

)

Property

time daysOfMonth

Type

Integer

Integer[]

Description

The hour of the day at which the notification is invoked. Possible values are integers from 0 to 23.

The days of the month on which the notification is invoked. Possible values are integers from 1 to 31, and -1 (which represents the last day of the month).

243

Analytics Notifications API Resource Reference

Threshold

Property

type

Type

String

Analytics Notification

Description

Specifies when the notification is invoked (other than date and time criteria).

Possible values are:

•

always

— Always invoke the notification

•

onError

— Invoke the notification when there is an error

•

condition

— Invoke the notification based on criteria described by conditions

Describes conditions that govern when the notification is invoked.

Specifies what action is taken when the notification is invoked.

conditions actions

Condition

Property

colName value operation

Condition[]

Action[]

Type

String

String

String

Description

The data field which is operated on.

The comparison value which is used by the operation.

The operation which is used to evaluate the condition. Possible values are:

•

equal

— colName

and value

are equal

•

notEqual

— colName

and value

are not equal

•

greaterThan

— colName

is greater than value

•

lessThan

— colName

is less than value

•

greaterThanEqual

— colName

is greater than or equal to value

•

lessThanEqual

— colName

is less than or equal to value

Action

Property

type

Type

String configuration

Configuration

Description

The type of action to perform when the notification is invoked. Possible values are:

•

sendEmail

— Send an email to recipients

Specifies important attributes for resources related to the notification.

244

Analytics Notifications API Resource Reference

Configuration

Property

recipients

Type

Recipient[]

Recipient

Property

id displayName

Type

String

String

WaveConfiguration

Property

anchor filter query datasets

Type

String

String

String

WaveDataset[]

WaveDataset

Property

id name namespace

Type

String

String

String

PUT Request Body

A notification object with desired changes.

Uses the same format as the GET response body.

PUT Response Body

An analytics notification object reflecting saved changes.

Uses the same format as the GET response body.

Description

Required. Id of the Wave dataset.

Optional. Developer name of the Wave dataset.

Optional. Namespace of the Wave dataset.

Analytics Notification

Description

A list of users, roles, and groups who receive the notification.

Description

Specifies who receives the notification. Valid values are the unique id of a user, role, or group.

The displayName

of the user, role, or group.

Description

Optional. The Id of the Wave dashboard widget to which the notification is anchored.

Optional. Description of selected filters at the time of notification creation.

Required. SAQL query which is run when the notification is invoked.

Required. Collection of Wave datasets referenced by the notification.

245

Analytics Notifications API Resource Reference

DELETE Response Body

The analytics notification is deleted, and can't be recovered.

Returns an empty response body.

Analytics Notification Limits

Check to see how many more analytics notifications you can create.

Syntax

URI

/vXX.X/analytics/notifications/limits?source=waveNotification

Formats

JSON

HTTP methods

Method

GET

Description

Check how many analytic notifications you have, and the maximum number you can have.

Analytics Notification Limits

Parameters

Parameter Description

source

Required for

GET

calls. Specifies what type of analytic notification to return limits for. Valid values are:

•

lightningReportSubscribe

— report subscriptions

•

waveNotification

— Wave notifications

GET Response Body

Property

max

Type

Integer remaining

Integer

Description

How many analytics notifications of the type specified by source

the user is allowed to create.

How many more analytics notifications of the type specified by source

the user can create before hitting the limit.

246

CHAPTER 10 Analytics Folders API Resource Reference

In this chapter ...

•

Folder Share

Information

•

Folder Shares

•

Folder Share by ID

•

Folder Share

Recipients

Use the Analytics Folders API to perform operations on report and dashboard folders. The Folders API is available in API version 41.0 and later.

Resources for the Analytics Folders API are available at

/services/data/

<latest API

version>/folders

. You can query each resource with an

HTTP

method.

Resource

Folder Share Information

/services/data/

<latest API

version>/folders/<folderid>

Supported

HTTP

Method

Description

GET

Returns the supported folder share types and the recipient and shares URLs.

Folder Shares

/services/data/

<latest API

version>/folders/<folderid>>/shares

GET

PUT

POST

Extracts a list of current folder shares (

GET

), adds new shares (

POST

), or replaces existing shares

(

PUT

).

Folder Share by ID

/services/data/

<latest API

version>/folders/<folderid>/shares/<shareid>

GET

PATCH

DELETE

For a specified share ID, extracts the folder share information

(

GET

), updates access level on the share

(

PATCH

), or deletes the share

(

DELETE

).

247

Analytics Folders API Resource Reference

Resource Supported

HTTP

Method

Description

Folder Share Recipients

/services/data/

<latest API

version>/folders/<folderid>/share-recipients?shareType=<shareType>

GET

Returns a list of folder share recipients.

248

Analytics Folders API Resource Reference

Folder Share Information

Return the supported folder share types and the recipient and shares URLs.

The following user permissions are needed to access this resource:

•

View Dashboards in Public Folders (for dashboard folders)

•

View Reports in Public Folders (for report folders)

Syntax

URI

/services/data/v41.0/folders/<folderId>

Formats

JSON

HTTP methods

Method

GET

Description

Returns the supported folder share types and the recipient and shares URLs.

Parameters

Parameter Description

folderId

Return data for this unique folder ID.

Folder Share Information

GET

Response Body

Property

id

Type

ID shareRecipientsUrl

ConnectUri sharesUrl

ConnectUri supportedShareTypes

List<ConnectFolderShareTypeEnum>

Description

Folder ID.

The URL for share recipients. Recipients are those that the folder can be shared with.

The share URL. This is the list of users, groups, or roles that the folder has already been shared with.

The list of share types. This is the list of share types that the folder can be shared with.

249

Analytics Folders API Resource Reference Folder Shares

Status Codes

Condition

Success

Missing perm

No such folder,

Unsupported folder type,

Unauthorized (missing access on a specific folder)

404

Code

200

403

Payload

FolderRepresentation

[ { "errorCode" : "FUNCTIONALITY_NOT_ENABLED",

"message" : "<message>]"}]

[ { "errorCode" : "<errorCode>", "message" :

"<message>" } ]

Output Example

{

"id" : 00lR0000000MQT5IAO

"shareRecipientsUrl" :

/services/data/v41.0/folders/00lR0000000MQT5IAO/share-recipients?shareType=User&limit=100

}

"sharesUrl" : /services/data/v41.0/folders/00lR0000000MQT5IAO/shares

"supportedShareTypes" : 0: user

1: group

Sample Raw Response

{

"id" : "00lR0000000MQT5IAO",

"shareRecipientsUrl" :

"/services/data/v41.0/folders/00lR0000000MQT5IAO/share-recipients?shareType=User&limit=100",

"sharesUrl" : "/services/data/v41.0/folders/00lR0000000MQT5IAO/shares",

"supportedShareTypes" : [ "user", "group" ]

}

Folder Shares

Extracts a list of current folder shares (

GET

), adds new shares (

POST

), or replaces existing shares (

PUT

).

The following user permissions are needed to access this resource:

•

GET

: View Dashboards in Public Folders (for dashboard folders), View Reports in Public Folders (for report folders)

•

POST

/

PUT

: Manage Dashboards in Public Folders (for dashboard folders), Manage Reports in Public Folders (for report folders)

Syntax

URI

/services/data/v41.0/folders/<folderId>/shares

250

Analytics Folders API Resource Reference Folder Shares

Formats

JSON

HTTP methods

Method

GET

PUT

POST

Description

Returns a list of current folder shares.

Creates new shares to replace the existing shares in the share list for the folder.

Creates new shares and appends them to the existing share list for the folder.

Parameters

Parameter Description

folderId

Perform the operation for this unique folder ID.

GET

Response Body

Property

accessType shareId shareType

Type

ConnectFolderAccessTypeEnum

ID

ConnectFolderShareTypeEnum

Description

Type of access: View, Edit, or Manage

Unique identifier of the share.

Type of share. The following are the supported share types.

•

Group. Users in a specified public group.

•

Role. Users with a specified role.

•

RoleAndSubordinates. Users with a specified role and users with a role subordinate to that role.

•

RoleAndSubordinatesInternal. Users with a specified role and users with a role subordinate to that role, except public portal users.

•

Organization. All internal users.

•

AllPrmUsers. All PRM Portal users.

•

User. The specified individual user.

•

PartnerUser. The specified individual user of a partner portal.

•

AllCspUsers. All Customer Success Portal users.

•

CustomerPortalUser. The specified individual user of a customer portal.

•

PortalRole. Users with a specified role in a portal.

•

PortalRoleAndSubordinates. Portal users with a specified role, and portal users with a role subordinate to that role.

251

Analytics Folders API Resource Reference Folder Shares

Property Type

sharedWithId sharedWithLabel url

ID

String

ConnectUri

Status Codes

Condition

Success

Missing perm

No such folder,

Unsupported folder type,

Unauthorized (missing access on a specific folder)

404

Code

200

403

Payload

Description

•

ChannelProgramGroup. PRM Portal users who are members of the specified channel programs and levels group.

Unique identifier of the share recipient.

Label of the share recipient.

URL of the share.

FolderShareCollectionRepresentation

[ { "errorCode" : "FUNCTIONALITY_NOT_ENABLED",

"message" : "<message>]"}]

[ { "errorCode" : "<errorCode>", "message" :

"<message>" } ]

Output Example 1

Sample raw response for a folder not shared with anyone.

{

}

“shares” : []

Output Example 2

Sample raw response for a folder shared with two users and a public group.

{

"shares" : [ {

"accessType" : "view",

"shareId" : "0AFR00000004LtpOAE",

"shareType" : "group",

"sharedWithId" : "00GR0000000Mi1nMAC",

"sharedWithLabel" : "Demo Group",

"url" : "/services/data/v41.0/folders/00lR0000000MQT5IAO/shares/0AFR00000004LtpOAE"

}, {

"accessType" : "edit",

"shareId" : "0AFR00000004LtkOAE",

"shareType" : "user",

"sharedWithId" : "005R0000000Kg8yIAC",

"sharedWithLabel" : "Brian Alison",

"url" : "/services/data/v41.0/folders/00lR0000000MQT5IAO/shares/0AFR00000004LtkOAE"

}, {

252

Analytics Folders API Resource Reference Folder Shares

"accessType" : "manage",

"shareId" : "0AFR00000004LtlOAE",

"shareType" : "user",

"sharedWithId" : "005R0000000Kg8cIAC",

} ]

}

"sharedWithLabel" : "Fred Williamson",

"url" : "/services/data/v41.0/folders/00lR0000000MQT5IAO/shares/0AFR00000004LtlOAE"

PUT/POST

Request Body

Query Param

Name

folder

Group

Object

Since

210

Values Description

FolderSharesInputRepresentation

Folder input representation containing a list of shares.

Status Codes

Condition

Success

Missing perm

No such folder,

Unsupported folder type,

Unauthorized (missing access on a specific folder)

404

Code

200

403

Sample Request Body

{

"shares" : [ {

"accessType" : "view",

"shareType" : "group",

"shareWithId" : "00GR0000000Mi1nMAC"

}, {

"accessType" : "edit",

"shareType" : "user",

"shareWithId" : "005R0000000Kg8yIAC"

}, {

"accessType" : "manage",

"shareType" : "user",

"shareWithId" : "005R0000000Kg8cIAC"

} ]

}

Payload

FolderSharesInputRepresentation

[ { "errorCode" : "FUNCTIONALITY_NOT_ENABLED",

"message" : "<message>]"}]

[ { "errorCode" : "<errorCode>", "message" :

"<message>" } ]

253

Analytics Folders API Resource Reference Folder Share by ID

Folder Share by ID

For a specified share ID, extracts folder share information (

GET

), updates the access level on the share (

PATCH

), or deletes the share

(

DELETE

).

The following user permissions are needed to access this resource:

•

GET

: View Dashboards in Public Folders (for dashboard folders), View Reports in Public Folders (for report folders)

•

PATCH

/

DELETE

: Manage Dashboards in Public Folders (for dashboard folders), Manage Reports in Public Folders (for report folders)

Syntax

URI

/services/data/v41.0/folders/<folderId>/shares/<shareId>

Formats

JSON

HTTP methods

Method

GET

PATCH

POST

Description

Returns information for the specified folder share.

Updates the access level on the specified folder share.

Deletes the specified folder share.

Parameters

Parameter Description

folderId

ID of the folder containing the share.

shareId

Perform the operation for this unique folder share ID.

GET

Response Body

Property

accessType shareId shareType

Type

ConnectFolderAccessTypeEnum

ID

ConnectFolderShareTypeEnum

Description

Type of access: View, Edit, or Manage

Unique identifier of the share.

Type of share. The following are the supported share types.

•

Group. Users in a specified public group.

•

Role. Users with a specified role.

•

RoleAndSubordinates. Users with a specified role and users with a role subordinate to that role.

254

Analytics Folders API Resource Reference Folder Share by ID

Property Type Description

•

RoleAndSubordinatesInternal. Users with a specified role and users with a role subordinate to that role, except public portal users.

•

Organization. All internal users.

•

AllPrmUsers. All PRM Portal users.

•

User. The specified individual user.

•

PartnerUser. The specified individual user of a partner portal.

•

AllCspUsers. All Customer Success Portal users.

•

CustomerPortalUser. The specified individual user of a customer portal.

•

PortalRole. Users with a specified role in a portal.

•

PortalRoleAndSubordinates. Portal users with a specified role, and portal users with a role subordinate to that role.

•

ChannelProgramGroup. PRM Portal users who are members of the specified channel programs and levels group.

Unique identifier of the share recipient.

Label of the share recipient.

URL of the share.

sharedWithId sharedWithLabel url

ID

String

ConnectUri

Status Codes

Condition

Success

Missing perm

No such folder,

Unsupported folder type,

Unauthorized (missing access on a specific folder)

404

Code

200

403

Output Example

{

“shareId” : “004xx000001Sy1GAAS”

“accessType” : “manage”,

“shareType” : “user”

“sharedWithId” : “005xx000001Sy1GAAS”

“sharedWithLabel” : “User1”

}

Payload

FolderShareRepresentation

[ { "errorCode" : "FUNCTIONALITY_NOT_ENABLED",

"message" : "<message>]"}]

[ { "errorCode" : "<errorCode>", "message" :

"<message>" } ]

255

Analytics Folders API Resource Reference

PATCH

Request Body

Query Param

Name

folder

Group

Object

Since

210

Values Description

FolderShareInputRepresentation

Folder share input representation.

Folder Share by ID

Status Codes

Condition

Success

Missing perm

No such folder,

Unsupported folder type,

Unauthorized (missing access on a specific folder)

404

Code

200

403

Payload

FolderShareRepresentation

[ { "errorCode" : "FUNCTIONALITY_NOT_ENABLED",

"message" : "<message>]"}]

[ { "errorCode" : "<errorCode>", "message" :

"<message>" } ]

Sample Request Body

{

"accessType" : "manage",

"shareType" : "user",

"shareWithId" : "005R0000000Kg8yIAC"

}

DELETE

Status Codes

Condition

Success

Missing perm

No such folder,

Unsupported folder type,

Unauthorized (missing access on a specific folder)

404

Code

200

403

Payload

NA

[ { "errorCode" : "FUNCTIONALITY_NOT_ENABLED",

"message" : "<message>]"}]

[ { "errorCode" : "<errorCode>", "message" :

"<message>" } ]

256

Analytics Folders API Resource Reference Folder Share Recipients

Folder Share Recipients

Return a list of folder share recipients.

The following user permissions are needed to access this resource:

•

View Dashboards in Public Folders (for dashboard folders)

•

View Reports in Public Folders (for report folders)

Syntax

URI

/services/data/v41.0/folders/<folderId>/share-recipients?shareType=<shareType>

Formats

JSON

HTTP methods

Method

GET

Description

Returns a list of share recipients with whom the folder can be shared.

Parameters

Parameter

folderId shareType searchTerm limit

Description

Return data for this unique folder ID.

Return data for the recipients of the specified type, such as user, group, or role.

Search to match share recipients names.

Limit to the number of search results.

Default

User

“ ”

100

GET

Response Body

Property Type

shareRecipients

List<FolderShareRecipientRepresentation> shareType

ConnectFolderShareTypeEnum

Description

List of recipients along with their share type.

Type of share. The following are the supported share types.

•

Group. Users in a specified public group.

•

Role. Users with a specified role.

Default

257

Analytics Folders API Resource Reference

Property Type

shareWithId

ID shareWithLabel

String

Status Codes

Condition

Success

Missing perm

No such folder,

Unsupported folder type,

Unauthorized (missing access on a specific folder)

404

Code

200

403

Folder Share Recipients

Description

•

RoleAndSubordinates. Users with a specified role and users with a role subordinate to that role.

•

RoleAndSubordinatesInternal. Users with a specified role and users with a role subordinate to that role, except public portal users.

•

Organization. All internal users.

•

AllPrmUsers. All PRM Portal users.

•

User. The specified individual user.

•

PartnerUser. The specified individual user of a partner portal.

•

AllCspUsers. All Customer Success

Portal users.

•

CustomerPortalUser. The specified individual user of a customer portal.

•

PortalRole. Users with a specified role in a portal.

•

PortalRoleAndSubordinates. Portal users with a specified role, and portal users with a role subordinate to that role.

•

ChannelProgramGroup. PRM Portal users who are members of the specified channel programs and levels group.

Default

Return the URL for share recipients.

Label of the folder share recipient.

Payload

FolderShareRecipientCollectionRepresentation

[ { "errorCode" : "FUNCTIONALITY_NOT_ENABLED",

"message" : "<message>]"}]

[ { "errorCode" : "<errorCode>", "message" :

"<message>" } ]

258

Analytics Folders API Resource Reference Folder Share Recipients

Output Example 1

Get share recipients of type user

.

/services/data/v41.0/folders/00lR0000000MQT5IAO/share-recipients?shareType=User

{

"shareRecipients" : [ {

"shareType" : "user",

"shareWithId" : "005R0000000Kg8wIAC",

"shareWithLabel" : "Hank Chen"

}, {

"shareType" : "user",

"shareWithId" : "005R0000000KkU6IAK",

"shareWithLabel" : "Integration User"

}, {

"shareType" : "user",

"shareWithId" : "005R0000000Kg8xIAC",

"shareWithLabel" : "Nadia Smith"

}, {

"shareType" : "user",

"shareWithId" : "005R0000000Kg8zIAC",

"shareWithLabel" : "Sarah Vasquez"

} ]

}

Output Example 2

Search for share recipients of type

Public Group

, with search term

Group

.

/services/data/v41.0/folders/00lR0000000MQT5IAO/share-recipients?shareType=Group&searchTerm=Group

{

"shareRecipients" : [ {

"shareType" : "group",

"shareWithId" : "00GR0000000EypUMAS",

"shareWithLabel" : "Finance"

}, {

"shareType" : "group",

"shareWithId" : "00GR0000000EypeMAC",

"shareWithLabel" : "Marketing"

}, {

"shareType" : "group",

"shareWithId" : "00GR0000000NvpIMAS",

"shareWithLabel" : "Products"

}, {

"shareType" : "group",

"shareWithId" : "00GR0000000EypZMAS",

"shareWithLabel" : "Sales"

}, {

"shareType" : "group",

"shareWithId" : "00GR0000000EypjMAC",

"shareWithLabel" : "Technology"

} ]

}

259

INDEX

A

Analytics Notifications API

GET a list of analytics notifications

111

,

115

GET a list of report types

44

Analytics Notifications API Examples

DELETE delete an analytics notification

115

POST create an analytics notification

113

PUT save an analytics notification

114

D

Dashboards API filtering results

78

getting dashboard metadata

100

getting list of dashboards

74

getting results

74

getting status

79

refreshing

80

returning details about dashboard components

85

saving a dashboard

80 ,

84

E

Examples Reports API

3

Examples: Dashboards API

73

I

Introduction

1

R

Reference

Dashboard error codes

232

Dashboard List

212

Dashboard Results

212

Dashboard Status

212

Folders

247

Notifications

234

Report Describe

117

Report Execute

117

Report Instances

117

Report List

117

Report Types

188 ,

204

Reports and Dashboards REST API report-level errors

185

Reports API Examples

POST create a report

4

Requirements and limitations

2

260

Resources

DELETE analytics notification

240

DELETE report

118

Detailed results

55

,

143

Fact map

55

Filter report results

55

, 143

GET analytics notifications limits

246

GET analytics notifications list

235

Get basic report metadata

129

GET dashboard describe

223 ,

231

GET dashboard list

213

GET dashboard results

213

GET dashboard status

229

Get extended report metadata

129

GET folder share recipients

257

GET folder share types

249

GET folder shares

250 ,

254

Get recent reports list

157

GET report data

55

,

143

GET report fields

172

GET report instance results

155

GET report instances

154

GET report type list

189

, 205

GET report type metadata

189

PATCH report

118

POST analytics notifications list

235

POST folder shares

250

,

254

POST report data

55 ,

143

POST report instance

150

,

154

POST Report Query Resource

161

PUT analytics notification

240

PUT folder shares

250

,

254

run report asynchronously

150

Summary level results

55

, 143

S

Salesforce Reports and Dashboards REST API asynchronous

50–51

dashboard, clone

108

dashboard, delete

109

filter reports

51

GET request

34 ,

41 ,

50

list report runs

50

POST request

51

recently viewed

54

report data

34

Index

Salesforce Reports and Dashboards REST API (continued) report list

54

report metadata

41

report, clone

70

report, delete

72

Salesforce Reports and Dashboards REST API (continued) report, query

58

report, save

69

synchronous

51

261