Salesforce Reports and

Dashboards REST API

Developer Guide
Version 36.0, Spring 16

@salesforcedocs
Last updated: January 28, 2016

 Copyright 20002016 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: Introducing the Salesforce Reports and Dashboards REST API . . . . . . . . . . . 1
Requirements and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Chapter 2: Understanding Reports REST API Resources . . . . . . . . . . . . . . . . . . . . . . . . 3

Run Reports Synchronously or Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Get Report Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
List Asynchronous Runs of a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Filter Reports on Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
List Recently Viewed Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Decode the Fact Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Save Changes to Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Clone Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Delete Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3: Understanding Dashboards REST API Resources . . . . . . . . . . . . . . . . . . . 27

Get List of Recently Used Dashboards
Get Dashboard Results . . . . . . . . . .
Filter Dashboard Results . . . . . . . . .
Get Dashboard Status . . . . . . . . . . .
Refresh a Dashboard . . . . . . . . . . .
Save a Dashboard . . . . . . . . . . . . .
Clone a Dashboard . . . . . . . . . . . .
Delete a Dashboard . . . . . . . . . . . .

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.

28
28
32
33
34
34
38
39

Chapter 4: Reports API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Execute Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Execute Async . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Instances List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Instance Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Report List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Report Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Chapter 5: Dashboards API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Dashboard List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Dashboard Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Dashboard Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Dashboard and Component Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Contents

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

CHAPTER 1

In this chapter ...

Requirements and
Limitations

Introducing the Salesforce Reports and

Dashboards REST API
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.

Introducing the 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 dont 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 organization 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 organization can request up to 200 dashboard refreshes per hour.
Your organization can request results for up to 5,000 dashboards per hour.
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.

CHAPTER 2 Understanding Reports REST API Resources

In this chapter ...

Run Reports
Synchronously or
Asynchronously

Get Report Metadata

List Asynchronous
Runs of a Report

Filter Reports on
Demand

List Recently Viewed

Reports

Decode the Fact Map

Save Changes to
Reports

Clone Reports

Delete Reports

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.

Understanding Reports REST API Resources

Run Reports Synchronously or Asynchronously

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 doesnt 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, theyre 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 youre 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" : {
"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" },

Understanding Reports REST API Resources

{ "label"
"value"
{ "label"
{ "label"
{ "label"
{ "label"
{ "label"
{ "label"
{ "label"
{ "label"

:
:
:
:
:
:
:
:
:
:

Run Reports Synchronously or Asynchronously

"$16,000.01",
{ "amount" : 16000.01, "currency" : null } },
"Word of mouth", "value" : "Word of mouth" },
"Need estimate", "value" : "Need estimate" },
"60%", "value" : 60},
"Q3-2015", "value" : "Q3-2015" },
"12", "value" : 12 },
"7/31/2015", "value" : "2015-07-31" },
"Fred Wiliamson", "value" : "005R0000000Hv5rIAC" },
"-", "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"
"Existing Business" } ],
"key" : "0",
"label" : "July 2015",
"value" : "2015-07-01"
},
{
"groupings" : [
{ "groupings" : [ ], "key"
"Existing Business" },
{ "groupings" : [ ], "key"
Business" } ],
"key" : "1",
"label" : "August 2015",
"value" : "2015-08-01"
},
{
"groupings" : [
{ "groupings" : [ ], "key"

: "0_0", "label" : "Existing Business", "value" :

: "1_0", "label" : "Existing Business", "value" :

: "1_1", "label" : "New Business", "value" : "New

: "2_0", "label" : "Existing Business", "value" :

Understanding Reports REST API Resources

Run Reports Synchronously or Asynchronously

"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" },
"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"

Understanding Reports REST API Resources

Run Reports Synchronously or Asynchronously

},
"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",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CLOSE_DATE",
"durationValue" : "THIS_FISCAL_QUARTER",
"endDate" : "2015-09-30",
"startDate" : "2015-07-01" },
"standardFilters" : [

Understanding Reports REST API Resources

Run Reports Synchronously or Asynchronously

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

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

Example of an asynchronous report run

1. This is a POST request, /services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances,
to the Execute Async resource for an asynchronous run requesting summary results.
{
"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,
"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,

Understanding Reports REST API Resources

Run Reports Synchronously or Asynchronously

"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",
"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" } ]
}
}

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" },

Understanding Reports REST API Resources

Run Reports Synchronously or Asynchronously

"allData" : true,
"factMap" : {
"2!0_0" : {
"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 } ]
} ]
},
...
"groupingsAcross" : {
"groupings" : [
...
]
},
"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" }

10

Understanding Reports REST API Resources

Run Reports Synchronously or Asynchronously

},
"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" },
"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",

11

Understanding Reports REST API Resources

Get Report Metadata

"reportBooleanFilter" : null,
"reportFilters" : [
{ "column" : "BucketField_36625466", "isRunPageEditable" : false, "operator" :
"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": {

12

Understanding Reports REST API Resources

Get Report Metadata

"CREATED": {
"filterValues": [],
"label": "Created By",
"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": {
"label": "Next Step",
"dataType": "string"
},
"BucketField_34840671": {
"label": "Industry",
"dataType": "string"
}
},
"aggregateColumnInfo": {
"RowCount": {

13

Understanding Reports REST API Resources

Get Report Metadata

"label": "Record Count",

"dataType": "int",
"downGroupingContext": null,
"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",

14

Understanding Reports REST API Resources

Get Report Metadata

"sortOrder": "Desc",
"dateGranularity": "FiscalQuarter"
}
],
"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

15

Understanding Reports REST API Resources

List Asynchronous Runs of a Report

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,
"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, its 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

16

Understanding Reports REST API Resources

Filter Reports on Demand

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"
},
{
"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",

17

Understanding Reports REST API Resources

Filter Reports on Demand

"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": []
}
}

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,

18

Understanding Reports REST API Resources

Filter Reports on Demand

"label": "1"
}
]
},
"7_1!T": {
"aggregates": [
{
"value":
"label":
},
{
"value":
"label":
}
]
},

24000000,
"$24,000,000"

1,
"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"
},
{
"value": "\"100,000\"",
"operator": "greaterThan",
"column": "SALES"
},
{
"value": "Manufacturing,Recreation",
"operator": "notEqual",
"column": "INDUSTRY"
}
],
"detailColumns": [
"RATING",
"LAST_UPDATE",
"SALES"
],
...

19

Understanding Reports REST API Resources

List Recently Viewed Reports

}
}

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

20

Understanding Reports REST API Resources

Decode the Fact Map

"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.
Report
format

Fact map key pattern

Tabular

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

Summary

<First level row grouping_second level row grouping_third level row

grouping>!T: T refers to the row grand total.

Matrix

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

grouping_second level column grouping>.

Each item in a row or column grouping is numbered starting with 0. Here are some examples of fact map keys:
Fact Map
Key

Description

0!T

The first item in the first-level grouping.

1!T

The second item in the first-level grouping.

0_0!T

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

0_1!T

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

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

21

Understanding Reports REST API Resources

Decode the Fact Map

Tabular Report Fact Map

Heres an example of an opportunities report in tabular format. Since tabular reports dont 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.

Fact Map Key

Description

0!T

Summary for the value of opportunities in the Prospecting stage.

22

Understanding Reports REST API Resources

1_0!T

Save Changes to Reports

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

Matrix Report Fact Map

Heres 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

Description

0!0

Total opportunity amount in the Prospecting stage in Q4 2010.

0_0!0_0

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

2_1!1_1

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

T!T

Grand total summary for the report.

SEE ALSO:
Execute Sync
Execute Async

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.

23

Understanding Reports REST API Resources

Save Changes to Reports

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" : {
"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" : {
...

24

Understanding Reports REST API Resources

Clone Reports

}
}

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."
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",

25

Understanding Reports REST API Resources

Delete Reports

"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CREATED_DATE",
"durationValue" : "CUSTOM",
"endDate" : null,
"startDate" : null },
"standardFilters" : null },
"reportTypeMetadata" : {
...
}
}

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.

26

CHAPTER 3 Understanding 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

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.

27

Understanding 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" : [ {

28

Understanding Dashboards REST API Resources

Get Dashboard Results

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

29

Understanding 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" : {

30

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

31

Understanding 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
} ], [ {

32

Understanding 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" :
"refreshDate" :
"refreshStatus"
}, {
"componentId" :
"refreshDate" :
"refreshStatus"
}, {
"componentId" :
"refreshDate" :
"refreshStatus"

: [ {
"01aD0000000J7M7",
"2014-03-10T17:26:07.000+0000",
: "IDLE"
"01aD0000000J7M9",
"2014-03-10T17:26:08.000+0000",
: "IDLE"
"01aD0000000J7MB",
"2014-03-10T17:26:09.000+0000",
: "IDLE"

33

Understanding 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",
}
}

34

Understanding Dashboards REST API Resources

Save a Dashboard

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,

35

Understanding 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" },

36

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

37

Understanding Dashboards REST API Resources

Clone a Dashboard

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

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.
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 },

38

Understanding Dashboards REST API Resources

Delete a Dashboard

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

39

CHAPTER 4 Reports API Resource Reference

In this chapter ...

Report

Describe

Execute Sync

Execute Async

Instances List

Instance Results

Report List

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

Supported Description
HTTP
Method

Report

PATCH

Saves changes to a report.

DELETE

Deletes a report.

Describe

GET

Gives report metadata. This includes information about fields that

are defined in the report as detail columns, summaries, custom
summary formulas, filters, and groupings.

Execute Sync

GET

Gives report summary level data with or without details.

POST

Returns specific results if you define dynamic filters, groupings, or

aggregates in the metadata of a POST request.

Execute Async

POST

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.

Instances List

GET

List of instances of a report that were requested for an

asynchronous run.

Instance Results

GET

Depending on the type of your request, gives summary level data

with or without details for an instance of a report run
asynchronously.

Report List

GET

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

POST

Makes a copy of a report.

40

Reports API Resource Reference

Report

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

Description

PATCH

Saves changes to a report. See this example.

DELETE

Deletes a report. See this example.

PATCH Request Body

Property

Type

Description

aggregates

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:
a!Amount represents the average for the Amount column.
s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount
column.
x!Amount represents the maximum value of the Amount
column.
s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.

buckets

Bucket field

Describes a bucket field.

chart

Chart[]

Details about the chart used in a report.

crossFilters

Cross filter on page

69[]

Cross filters applied to the report.

41

Reports API Resource Reference

Report

Property

Type

Description

customSummaryFormula

Custom summary
formula

Describes a custom summary formulas.

currency

String

Report currency, such as USD, EUR, GBP, for an organization that has
Multi-Currency enabled. Value is null if the organization does not
have Multi-Currency enabled.

detailColumns

Array of strings

Unique API names for the fields that have detailed data.

developerName

String

Report API name.

division

String

Determines the division of records to include in the report. For example,

West Coast and East Coast.
Available only if your organization uses divisions to segment data and
you have the Affected by Divisions permission. If you do not have the
Affected by Divisions permission, your reports include records in all
divisions.

folderId

String

ID of the folder that contains the report.

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.

groupingsAcross

Groupings across[]

Unique identities for each column grouping in a report. The identity is:
An empty array for reports in summary format as it cant have
column groupings.
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for a column
grouping.

groupingsDown

Groupings down[]

Unique identities for each row grouping in a report. The identity is:
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for grouping.

hasDetailRows

Boolean

Indicates whether to include detailed data with the summary data.

hasRecordCount

Boolean

Indicates whether the report shows the record count.

historicalSnapshotDates Array of strings

List of historical snapshot dates.

id

String

Unique report ID.

name

String

Display name of the report.

reportBooleanFilter

String

Logic to parse custom field filters. Value is null when filter logic is
not specified.
This is an example of a report filtered to show opportunities for accounts
that are either of customer or partner type OR their annual revenue

42

Reports API Resource Reference

Property

Report

Type

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"
}
]
}
}

reportFilters

Filter details[]

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

reportFormat

String

Format of the report. Value can be:

TABULAR
SUMMARY
MATRIX

reportType

Report type

Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
label: Of type string, this is the display name of the report type.

scope

String

Defines the scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities you own,
or opportunities your team owns. Valid values depend on the report
type.

showGrandTotal

Boolean

Indicates whether the report shows the grand total.

showSubtotals

Boolean

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

totals.

43

Reports API Resource Reference

Report

Property

Type

Description

sortBy

String

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

standardDateFilter

Array of strings

Standard date filters available in reports. Each standard date filter

contains the following properties:
column: API name of the date field on which you filter the report data.
durationValue: The range for which you want to run the report.

The value is a date literal or 'CUSTOM.'

startDate: Start date.
endDate: End date.
standardFilters

Array of strings

List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.

topRows

Top rows

Describes a row limit filter applied to the report.

PATCH Response Body

Property

Type

Description

reportMetadata

Report metadata

Unique identifiers for groupings and summaries.

reportTypeMetadata

Report type metadata

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

reportExtendedMetadata Report extended

Additional information about summaries and groupings.

metadata

Report metadata
Property

Type

Description

aggregates

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:
a!Amount represents the average for the Amount column.
s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount
column.
x!Amount represents the maximum value of the Amount
column.

44

Reports API Resource Reference

Property

Report

Type

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.

buckets

Bucket field

Describes a bucket field.

chart

Chart[]

Details about the chart used in a report.

crossFilters

Cross filter on page

56[]

Cross filters applied to the report.

customSummaryFormula

Custom summary
formula

Describes a custom summary formulas.

currency

String

Report currency, such as USD, EUR, GBP, for an organization that has
Multi-Currency enabled. Value is null if the organization does not
have Multi-Currency enabled.

detailColumns

Array of strings

Unique API names for the fields that have detailed data.

developerName

String

Report API name.

division

String

Determines the division of records to include in the report. For

example, West Coast and East Coast.
Available only if your organization uses divisions to segment data
and you have the Affected by Divisions permission. If you do not
have the Affected by Divisions permission, your reports include
records in all divisions.

folderId

String

ID of the folder that contains the report.

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.

groupingsAcross

Groupings across[]

Unique identities for each column grouping in a report. The identity

is:
An empty array for reports in summary format as it cant have
column groupings.
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for a column
grouping.

groupingsDown

Groupings down[]

Unique identities for each row grouping in a report. The identity is:
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for grouping.

hasDetailRows

Boolean

Indicates whether to include detailed data with the summary data.

45

Reports API Resource Reference

Report

Property

Type

Description

hasRecordCount

Boolean

Indicates whether the report shows the record count.

historicalSnapshotDates Array of strings

List of historical snapshot dates.

id

String

Unique report ID.

name

String

Display name of the report.

reportBooleanFilter

String

Logic to parse custom field filters. Value is null when filter logic is
not specified.
This is an example of a report filtered to show opportunities for
accounts that are either of customer or partner type OR their annual
revenue exceeds 100K AND they are medium or large sized
businesses. The filters are processed by the logic, (1 OR 2) AND 3.
{
...
"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"
}
]
}
}

reportFilters

Filter details[]

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

reportFormat

String

Format of the report. Value can be:

TABULAR
SUMMARY
MATRIX

reportType

Report type

Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.

46

Reports API Resource Reference

Property

Report

Type

Description
label: Of type string, this is the display name of the report type.

scope

String

Defines the scope of the data on which you run the report. For
example, you can run the report against all opportunities,
opportunities you own, or opportunities your team owns. Valid values
depend on the report type.

showGrandTotal

Boolean

Indicates whether the report shows the grand total.

showSubtotals

Boolean

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

totals.

sortBy

String

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

standardDateFilter

Array of strings

Standard date filters available in reports. Each standard date filter

contains the following properties:
column: API name of the date field on which you filter the report

data.
durationValue: The range for which you want to run the report.

The value is a date literal or 'CUSTOM.'

startDate: Start date.
endDate: End date.
standardFilters

Array of strings

List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the
Opportunity object are Show, Opportunity Status, and Probability.
This list appears as name-value string pairs.

topRows

Top rows

Describes a row limit filter applied to the report.

Property

Type

Description

chartType

String

Type of chart.

groupings

String

Report grouping.

hasLegend

Boolean

Indicates whether the report has a legend.

showChartValues

Boolean

Indicates whether the report shows chart values.

summaries

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:

Chart

a!Amount represents the average for the Amount column.

s!Amount represents the sum of the Amount column.

47

Reports API Resource Reference

Property

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.

summaryAxisLocations

String

Specifies the axis that shows the summary values. Valid values are X
and Y.

title

String

Name of the chart.

Property

Type

Description

name

String

API name of the field used as a row grouping.

sortOrder

String

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

Groupings down

Asc for ascending order.

Desc for descending order.
dateGranularity

String

Interval set on a date field thats used as a row grouping. Value can
be:
Day
Calendar Week
Calendar Month
Calendar Quarter
Calendar Year
Fiscal Quarter
Fiscal Year
Calendar Month in Year
Calendar Day in Month

sortAggregate

String

Summary field thats used to sort data within a grouping in a report

thats 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": [

48

Reports API Resource Reference

Property

Report

Type

Description
{
"name": "USERS.NAME",
"sortOrder": "Desc",
"dateGranularity": "None",
"sortAggregate": "s!SALES"
}
]
}

Groupings across
Property

Type

Description

name

String

API name of the field used as a column grouping.

sortOrder

String

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

be:
Asc for ascending order.
Desc for descending order.

dateGranularity

String

Interval set on a date field used as a column grouping. Value can be:
Day
Calendar Week
Calendar Month
Calendar Quarter
Calendar Year
Fiscal Quarter
Fiscal Year
Calendar Month in Year
Calendar Day in Month

Filter details
Property

Type

Description

column

String

Unique API name for the field thats being filtered.

isRunPageEditable

Boolean

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

operator

String

Unique API name for the condition used to filter a field such as
greater than or not equal to. Filter conditions depend on the data
type of the field.

value

String

Value by which a field is filtered. For example, the field Age can be
filtered by a numeric value.

49

Reports API Resource Reference

Report

Report type metadata

Property

Type

Description

categories

Categories[]

All fields in the report type organized by section.

dataTypeFilterOperatorMap

Filter operator
reference

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

types 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

Division info[]

Default division and list of all possible record-level divisions

that can be used in a report.

scopeInfo

Scope info[]

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 List of standard date filters available in reports.

duration groups[]
Array of strings

standardFilterInfos

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

Type

Description

label

String

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.

columns

Column map

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

50

Reports API Resource Reference

Report

Column map
Property

Type

Description

label

String

Display name of a field.

filterValues

String array

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

dataType

String

Data type of the field.

filterable

Boolean

False means that the field is of a type that cant be filtered. For
example, fields of the type Encrypted Text cant be filtered.

Property

Type

Description

defaultValue

String

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

values

String

All division values. Division values have two properties:

Division info

label: Display name of a division.

name: Unique API name of a division.

Scope Info
Property

Type

Description

defaultValue

String

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

values

Array of strings

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.

51

Reports API Resource Reference

Report

Standard date filter duration groups

Property

Type

Description

label

String

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

Type

Description

endDate

String

End date of a date filter.

label

String

Display name of a date filter. Valid date filters are relative date
filterslike Current FY and Current FQand custom date
filters.

startDate

String

Start date of a date filter.

value

String

API name of a date filter. Valid date filters are relative date filterslike
THIS_FISCAL_YEAR and NEXT_FISCAL_QUARTERand
custom date filters.

Property

Type

Description

aggregateColumnInfo

Aggregate column
information

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.

detailColumnInfo

Detail column
information

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.

groupingColumnInfo

Grouping column
information

Map of each row or column grouping to its metadata. Contains values

for each grouping identified in the groupingsDown and
groupingsAcross list.

Report extended metadata

Aggregate column information

Property

Type

Description

label

String

Display name for record count, or the summarized or custom

summary formula field.

52

Reports API Resource Reference

Report

Property

Type

Description

dataType

String

Data type of the summarized or custom summary formula field.

acrossGroupingContext

String

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

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"
},
}
}
}

53

Reports API Resource Reference

Property

Report

Type

Description

Property

Type

Description

label

String

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.

dataType

String

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

Detail column information

string
boolean
double
int
percent
currency
date
datetime
time
picklist
multipicklist
id
reference
textarea
phone
combobox
url
email
html

Grouping column information

Property

Type

Description

label

String

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

54

Reports API Resource Reference

Report

Property

Type

Description

dataType

String

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

groupingLevel

Integer

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.

Bucket field
Property

Type

Description

bucketType

BucketType

The type of bucket. Possible values are number, percent, and

picklist

developerName

String

API name of the bucket.

label

String

User-facing name of the bucket.

nullTreatedAsZero

Boolean

Specifies whether null values are converted to zero (true) or not

(false).

55

Reports API Resource Reference

Report

Property

Type

Description

otherBucketLabel

String

Name of the fields grouped as Other (in buckets of BucketType

PICKLIST).

sourceColumnName

String

Name of the bucketed field.

values

Array of
BucketTypeValues

Describes the values included in the bucket field..

Property

Type

Description

label

String

The user-facing name of the bucket.

sourceDimensionValues

String

A list of the values from the source field included in this bucket
category (in buckets of type PICKLIST and buckets of type TEXT).

rangeUpperBound

Double

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

Property

Type

Description

criteria

Array of Filter details[] Information about how to filter the relatedEntity. Use to relate
the primary entity with a subset of the relatedEntity.

includesObject

Boolean

Specifies whether objects returned have a relationship with the

relatedEntity (true) or not (false).

primaryEntityField

String

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

relatedEntity

String

The name of the object that the primaryEntityField is

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

relatedEntityJoinField

String

The name of the field used to join the primaryEntityField

and relatedEntity.

Property

Type

Description

label

String

The user-facing name of the custom summary formula.

description

String

The user-facing description of the custom summary formula.

formulaType

String

The format of the numbers in the custom summary formula. Possible

values are number, currency, and percent.

decimalPlaces

Integer

The number of decimal places to include in numbers.

Bucket field value

Cross filter

Custom summary formula

56

Reports API Resource Reference

Describe

Property

Type

Description

downGroup

String

The name of a row grouping when the downGroupType is

CUSTOM. Null otherwise.

downGroupType

String

Where to display the aggregate of the custom summary formula.

Possible values are all, custom, and grand_total.

acrossGroup

String

The name of a column grouping when the accrossGroupType

is CUSTOM. Null otherwise.

acrossGroupType

String

Where to display the aggregate of the custom summary formula.

Possible values are all, custom, and grand_total.

formula

String

The operations performed on values in the custom summary formula.

Property

Type

Description

rowLimit

Integer

The number of rows returned in the report.

direction

String

The sort order of the report rows.

Top 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

Description

GET

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

57

Reports API Resource Reference

Describe

Response Body
Property

Type

Description

reportMetadata

Report metadata

Unique identifiers for groupings and summaries.

reportTypeMetadata

Report type metadata

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

reportExtendedMetadata Report extended

Additional information about summaries and groupings.

metadata

Report metadata
Property

Type

Description

aggregates

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:
a!Amount represents the average for the Amount column.
s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount
column.
x!Amount represents the maximum value of the Amount
column.
s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity
is a combination of the summary type and the field ID.

buckets

Bucket field

Describes a bucket field.

chart

Chart[]

Details about the chart used in a report.

crossFilters

Cross filter on page

69[]

Cross filters applied to the report.

customSummaryFormula

Custom summary
formula

Describes a custom summary formulas.

currency

String

Report currency, such as USD, EUR, GBP, for an organization that has
Multi-Currency enabled. Value is null if the organization does not
have Multi-Currency enabled.

detailColumns

Array of strings

Unique API names for the fields that have detailed data.

developerName

String

Report API name.

division

String

Determines the division of records to include in the report. For

example, West Coast and East Coast.
Available only if your organization uses divisions to segment data
and you have the Affected by Divisions permission. If you do not

58

Reports API Resource Reference

Property

Describe

Type

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

folderId

String

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.

groupingsAcross

Groupings across[]

Unique identities for each column grouping in a report. The identity

is:
An empty array for reports in summary format as it cant have
column groupings.
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for a column
grouping.

groupingsDown

Groupings down[]

Unique identities for each row grouping in a report. The identity is:
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for grouping.

hasDetailRows

Boolean

Indicates whether to include detailed data with the summary data.

hasRecordCount

Boolean

Indicates whether the report shows the record count.

historicalSnapshotDates Array of strings

List of historical snapshot dates.

id

String

Unique report ID.

name

String

Display name of the report.

reportBooleanFilter

String

Logic to parse custom field filters. Value is null when filter logic is
not specified.
This is an example of a report filtered to show opportunities for
accounts that are either of customer or partner type OR their annual
revenue exceeds 100K AND they are medium or large sized
businesses. The filters are processed by the logic, (1 OR 2) AND 3.
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{

59

Reports API Resource Reference

Property

Describe

Type

Description
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}

reportFilters

Filter details[]

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

reportFormat

String

Format of the report. Value can be:

TABULAR
SUMMARY
MATRIX

reportType

Report type

Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
label: Of type string, this is the display name of the report type.

scope

String

Defines the scope of the data on which you run the report. For
example, you can run the report against all opportunities,
opportunities you own, or opportunities your team owns. Valid values
depend on the report type.

showGrandTotal

Boolean

Indicates whether the report shows the grand total.

showSubtotals

Boolean

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

totals.

sortBy

String

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

standardDateFilter

Array of strings

Standard date filters available in reports. Each standard date filter

contains the following properties:
column: API name of the date field on which you filter the report

data.
durationValue: The range for which you want to run the report.

The value is a date literal or 'CUSTOM.'

startDate: Start date.
endDate: End date.

60

Reports API Resource Reference

Describe

Property

Type

Description

standardFilters

Array of strings

List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the
Opportunity object are Show, Opportunity Status, and Probability.
This list appears as name-value string pairs.

topRows

Top rows

Describes a row limit filter applied to the report.

Property

Type

Description

chartType

String

Type of chart.

groupings

String

Report grouping.

hasLegend

Boolean

Indicates whether the report has a legend.

showChartValues

Boolean

Indicates whether the report shows chart values.

summaries

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:

Chart

a!Amount represents the average for the Amount column.

s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount
column.
x!Amount represents the maximum value of the Amount
column.
s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity
is a combination of the summary type and the field ID.
summaryAxisLocations

String

Specifies the axis that shows the summary values. Valid values are X
and Y.

title

String

Name of the chart.

Property

Type

Description

name

String

API name of the field used as a row grouping.

sortOrder

String

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

Groupings down

Asc for ascending order.

Desc for descending order.

61

Reports API Resource Reference

Describe

Property

Type

Description

dateGranularity

String

Interval set on a date field thats used as a row grouping. Value can
be:
Day
Calendar Week
Calendar Month
Calendar Quarter
Calendar Year
Fiscal Quarter
Fiscal Year
Calendar Month in Year
Calendar Day in Month

sortAggregate

String

Summary field thats used to sort data within a grouping in a report

thats 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

Type

Description

name

String

API name of the field used as a column grouping.

sortOrder

String

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

be:
Asc for ascending order.
Desc for descending order.

dateGranularity

String

Interval set on a date field used as a column grouping. Value can be:
Day
Calendar Week

62

Reports API Resource Reference

Property

Describe

Type

Description
Calendar Month
Calendar Quarter
Calendar Year
Fiscal Quarter
Fiscal Year
Calendar Month in Year
Calendar Day in Month

Filter details
Property

Type

Description

column

String

Unique API name for the field thats being filtered.

isRunPageEditable

Boolean

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

operator

String

Unique API name for the condition used to filter a field such as
greater than or not equal to. Filter conditions depend on the data
type of the field.

value

String

Value by which a field is filtered. For example, the field Age can be
filtered by a numeric value.

Report type metadata

Property

Type

Description

categories

Categories[]

All fields in the report type organized by section.

dataTypeFilterOperatorMap

Filter operator
reference

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

types 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

Division info[]

Default division and list of all possible record-level divisions

that can be used in a report.

scopeInfo

Scope info[]

Scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities

63

Reports API Resource Reference

Describe

Property

Type

Description
you own, or opportunities your team owns. Valid values
depend on the report type.

standardDateFilterDurationGroups Standard date filter List of standard date filters available in reports.

duration groups[]
Array of strings

standardFilterInfos

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

Type

Description

label

String

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.

columns

Column map

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

Property

Type

Description

label

String

Display name of a field.

filterValues

String array

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 cant be determined.
Filter values have two properties:

Column map

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

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

String

Data type of the field.

filterable

Boolean

False means that the field is of a type that cant be filtered. For
example, fields of the type Encrypted Text cant be filtered.

64

Reports API Resource Reference

Describe

Division info
Property

Type

Description

defaultValue

String

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

values

String

All division values. Division values have two properties:

label: Display name of a division.
name: Unique API name of a division.

Scope Info
Property

Type

Description

defaultValue

String

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

values

Array of strings

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

Type

Description

label

String

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

Type

Description

endDate

String

End date of a date filter.

label

String

Display name of a date filter. Valid date filters are relative date
filterslike Current FY and Current FQand custom date
filters.

startDate

String

Start date of a date filter.

65

Reports API Resource Reference

Describe

Property

Type

Description

value

String

API name of a date filter. Valid date filters are relative date filterslike
THIS_FISCAL_YEAR and NEXT_FISCAL_QUARTERand
custom date filters.

Property

Type

Description

aggregateColumnInfo

Aggregate column
information

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.

detailColumnInfo

Detail column
information

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.

groupingColumnInfo

Grouping column
information

Map of each row or column grouping to its metadata. Contains values

for each grouping identified in the groupingsDown and
groupingsAcross list.

Report extended metadata

Aggregate column information

Property

Type

Description

label

String

Display name for record count, or the summarized or custom

summary formula field.

dataType

String

Data type of the summarized or custom summary formula field.

acrossGroupingContext

String

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"
},
}
}
}

66

Reports API Resource Reference

Describe

Property

Type

Description

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"
},
}
}
}

Detail column information

Property

Type

Description

label

String

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.

dataType

String

The data type of the field that has detailed data. Possible values are:
string
boolean
double
int
percent
currency

67

Reports API Resource Reference

Property

Describe

Type

Description
date
datetime
time
picklist
multipicklist
id
reference
textarea
phone
combobox
url
email
html

Grouping column information

Property

Type

Description

label

String

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

dataType

String

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

68

Reports API Resource Reference

Property

Describe

Type

Description
html

groupingLevel

Integer

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.

Bucket field
Property

Type

Description

bucketType

BucketType

The type of bucket. Possible values are number, percent, and

picklist

developerName

String

API name of the bucket.

label

String

User-facing name of the bucket.

nullTreatedAsZero

Boolean

Specifies whether null values are converted to zero (true) or not

(false).

otherBucketLabel

String

Name of the fields grouped as Other (in buckets of BucketType

PICKLIST).

sourceColumnName

String

Name of the bucketed field.

values

Array of
BucketTypeValues

Describes the values included in the bucket field..

Property

Type

Description

label

String

The user-facing name of the bucket.

sourceDimensionValues

String

A list of the values from the source field included in this bucket
category (in buckets of type PICKLIST and buckets of type TEXT).

rangeUpperBound

Double

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

Property

Type

Description

criteria

Array of Filter details[] Information about how to filter the relatedEntity. Use to relate
the primary entity with a subset of the relatedEntity.

Bucket field value

Cross filter

69

Reports API Resource Reference

Describe

Property

Type

Description

includesObject

Boolean

Specifies whether objects returned have a relationship with the

relatedEntity (true) or not (false).

primaryEntityField

String

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

relatedEntity

String

The name of the object that the primaryEntityField is

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

relatedEntityJoinField

String

The name of the field used to join the primaryEntityField

and relatedEntity.

Property

Type

Description

label

String

The user-facing name of the custom summary formula.

description

String

The user-facing description of the custom summary formula.

formulaType

String

The format of the numbers in the custom summary formula. Possible

values are number, currency, and percent.

decimalPlaces

Integer

The number of decimal places to include in numbers.

downGroup

String

The name of a row grouping when the downGroupType is

CUSTOM. Null otherwise.

downGroupType

String

Where to display the aggregate of the custom summary formula.

Possible values are all, custom, and grand_total.

acrossGroup

String

The name of a column grouping when the accrossGroupType

is CUSTOM. Null otherwise.

acrossGroupType

String

Where to display the aggregate of the custom summary formula.

Possible values are all, custom, and grand_total.

formula

String

The operations performed on values in the custom summary formula.

Property

Type

Description

rowLimit

Integer

The number of rows returned in the report.

direction

String

The sort order of the report rows.

Custom summary formula

Top rows

SEE ALSO:
Execute Sync
Execute Async

70

Reports API Resource Reference

Execute Sync

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.

Resource URL
/services/data/<latest API version>/analytics/reports/<report ID>

Formats
JSON

HTTP Methods
Method

Description

GET

Get report results. See this example.

POST

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

POST Request Body

Property

Type

Description

aggregates

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:
a!Amount represents the average for the Amount column.
s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount
column.
x!Amount represents the maximum value of the Amount
column.
s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.

buckets

Bucket field

Describes a bucket field.

chart

Chart[]

Details about the chart used in a report.

crossFilters

Cross filter on page

69[]

Cross filters applied to the report.

customSummaryFormula

Custom summary
formula

Describes a custom summary formulas.

71

Reports API Resource Reference

Execute Sync

Property

Type

Description

currency

String

Report currency, such as USD, EUR, GBP, for an organization that has
Multi-Currency enabled. Value is null if the organization does not
have Multi-Currency enabled.

detailColumns

Array of strings

Unique API names for the fields that have detailed data.

developerName

String

Report API name.

division

String

Determines the division of records to include in the report. For example,

West Coast and East Coast.
Available only if your organization uses divisions to segment data and
you have the Affected by Divisions permission. If you do not have the
Affected by Divisions permission, your reports include records in all
divisions.

folderId

String

ID of the folder that contains the report.

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.

groupingsAcross

Groupings across[]

Unique identities for each column grouping in a report. The identity is:
An empty array for reports in summary format as it cant have
column groupings.
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for a column
grouping.

groupingsDown

Groupings down[]

Unique identities for each row grouping in a report. The identity is:
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for grouping.

hasDetailRows

Boolean

Indicates whether to include detailed data with the summary data.

hasRecordCount

Boolean

Indicates whether the report shows the record count.

historicalSnapshotDates Array of strings

List of historical snapshot dates.

id

String

Unique report ID.

name

String

Display name of the report.

reportBooleanFilter

String

Logic to parse custom field filters. Value is null when filter logic is
not specified.
This is an example of a report filtered to show opportunities for accounts
that are either of customer or partner type OR their annual revenue

72

Reports API Resource Reference

Property

Execute Sync

Type

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"
}
]
}
}

reportFilters

Filter details[]

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

reportFormat

String

Format of the report. Value can be:

TABULAR
SUMMARY
MATRIX

reportType

Report type

Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
label: Of type string, this is the display name of the report type.

scope

String

Defines the scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities you own,
or opportunities your team owns. Valid values depend on the report
type.

showGrandTotal

Boolean

Indicates whether the report shows the grand total.

showSubtotals

Boolean

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

totals.

73

Reports API Resource Reference

Execute Sync

Property

Type

Description

sortBy

String

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

standardDateFilter

Array of strings

Standard date filters available in reports. Each standard date filter

contains the following properties:
column: API name of the date field on which you filter the report data.
durationValue: The range for which you want to run the report.

The value is a date literal or 'CUSTOM.'

startDate: Start date.
endDate: End date.
standardFilters

Array of strings

List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.

topRows

Top rows

Describes a row limit filter applied to the report.

Response Body
Property

Type

Description

attributes

Attributes

Key report attributes and child resource URLs.

allData

Boolean

When True, all report results are returned.

When False, results are returned for the same number of rows as
a report run in Salesforce.
Note: For reports that have too many records, use filters to
refine results.

factMap

Fact map

Summary level data or both summary and detailed data for each row
or column grouping. Detailed data is available if hasDetailRows
is true.
Each row or column grouping is represented by combination of row
and column grouping keys defined in Groupings down and
Groupings across.
See these examples of fact map keys.

groupingsAcross

Groupings across

Collection of column groupings, keys, and their values.

groupingsDown

Groupings down

Collection of row groupings, keys, and their values.

hasDetailRows

Boolean

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

74

Reports API Resource Reference

Property

Execute Sync

Type

Description
When false, the fact map returns summary values.

reportExtendedMetadata

Report extended
metadata

Additional information about columns, summaries, and groupings.

reportMetadata

Report metadata

Unique identifiers for groupings and summaries.

Attributes
Property

Type

Description

describeUrl

String

Resource URL to get report metadata.

instancesUrl

String

Resource URL to run a report asynchronously. The report can be

run with or without filters to get summary or both summary and
detailed data. Results of each instance of the report run are stored
under this URL.

type

String

API resource format.

reportName

String

Display name of the report.

reportId

String

Unique report ID.

Property

Type

Description

rows

Data cells[]

Array of detailed report data listed in the order of the detail

columns provided by the report metadata.

aggregates

Aggregates[]

Summary level data including record count for a report.

Property

Type

Description

value

Detail column info

data type

The value of a specified cell.

label

String

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

report.

Property

Type

Description

value

Number

Numeric value of the summary data for a specified cell.

Fact map

Data cells

Aggregates

75

Reports API Resource Reference

Execute Sync

Property

Type

Description

label

String

Formatted summary data for a specified cell.

Property

Type

Description

groupings

Groupings[]

Information for each column grouping as a list.

Property

Type

Description

value

String

Value of the field used as a row or column grouping. The value

depends on the fields data type.

Groupings across

Groupings

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 owners Chatter profile page can be a grouping
value.
key

String

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

by the fact map to specify data values within each grouping.

label

String

Display name of a row or column grouping. For date and time

fields, the label is the localized date or time.

groupings

Array

Second or third level row or column groupings. If there are none,

the value is an empty array.

dategroupings

Array

Start date and end date of the interval defined by date

granularity.

76

Reports API Resource Reference

Execute Async

Groupings down
Property

Type

Description

groupings

Groupings[]

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

Description

POST

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

Type

Description

aggregates

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:
a!Amount represents the average for the Amount column.
s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount
column.
x!Amount represents the maximum value of the Amount
column.

77

Reports API Resource Reference

Property

Execute Async

Type

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.

buckets

Bucket field

Describes a bucket field.

chart

Chart[]

Details about the chart used in a report.

crossFilters

Cross filter on page

69[]

Cross filters applied to the report.

customSummaryFormula

Custom summary
formula

Describes a custom summary formulas.

currency

String

Report currency, such as USD, EUR, GBP, for an organization that has
Multi-Currency enabled. Value is null if the organization does not
have Multi-Currency enabled.

detailColumns

Array of strings

Unique API names for the fields that have detailed data.

developerName

String

Report API name.

division

String

Determines the division of records to include in the report. For example,

West Coast and East Coast.
Available only if your organization uses divisions to segment data and
you have the Affected by Divisions permission. If you do not have the
Affected by Divisions permission, your reports include records in all
divisions.

folderId

String

ID of the folder that contains the report.

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.

groupingsAcross

Groupings across[]

Unique identities for each column grouping in a report. The identity is:
An empty array for reports in summary format as it cant have
column groupings.
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for a column
grouping.

groupingsDown

Groupings down[]

Unique identities for each row grouping in a report. The identity is:
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for grouping.

hasDetailRows

Boolean

Indicates whether to include detailed data with the summary data.

hasRecordCount

Boolean

Indicates whether the report shows the record count.

78

Reports API Resource Reference

Property

Execute Async

Type

historicalSnapshotDates Array of strings

Description
List of historical snapshot dates.

id

String

Unique report ID.

name

String

Display name of the report.

reportBooleanFilter

String

Logic to parse custom field filters. Value is null when filter logic is
not specified.
This is an example of a report filtered to show opportunities for accounts
that are either of customer or partner type OR their annual revenue
exceeds 100K AND they are medium or large sized businesses. The
filters are processed by the logic, (1 OR 2) AND 3.
{
...
"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"
}
]
}
}

reportFilters

Filter details[]

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

reportFormat

String

Format of the report. Value can be:

TABULAR
SUMMARY
MATRIX

reportType

Report type

Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
label: Of type string, this is the display name of the report type.

79

Reports API Resource Reference

Execute Async

Property

Type

Description

scope

String

Defines the scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities you own,
or opportunities your team owns. Valid values depend on the report
type.

showGrandTotal

Boolean

Indicates whether the report shows the grand total.

showSubtotals

Boolean

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

totals.

sortBy

String

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

standardDateFilter

Array of strings

Standard date filters available in reports. Each standard date filter

contains the following properties:
column: API name of the date field on which you filter the report data.
durationValue: The range for which you want to run the report.

The value is a date literal or 'CUSTOM.'

startDate: Start date.
endDate: End date.
standardFilters

Array of strings

List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.

topRows

Top rows

Describes a row limit filter applied to the report.

Response Body
Property

Type

Description

id

String

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

status

String

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.

url

String

URL where results of the report run for that instance are stored. The value is null if the
report couldnt be run because of an error.

ownerId

String

API name of the user that created the instance.

80

Reports API Resource Reference

Instances List

Property

Type

Description

completionDate

Date, time
string

Date, time when the instance of the report run finished. Only available if the report instance
ran successfully or couldnt be run because of an error. Date-time information is in ISO-8601
format.

hasDetailRows

Boolean

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.

requestDate

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

Description

GET

Return a list of asynchronous runs of a report. See this example.

Response Body
Property

Type

Description

id

String

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.

status

String

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

81

Reports API Resource Reference

Property

Instance Results

Type

Description
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

String

URL where results of the report run for that instance are stored. The value is
null if the report couldnt be run because of an error.

ownerId

String

API name of the user that created the instance.

hasDetailRows

Boolean

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.

completionDate

Date, time string

Date, time when the instance of the report run finished. Only available if the
report instance ran successfully or couldnt be run because of an error. Date-time
information is in ISO-8601 format.

requestDate

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

Formats
JSON

82

Reports API Resource Reference

Instance Results

HTTP Methods
Method

Description

GET

Retrieves results of an asynchronous report run. See this example.

Response Body
Property

Type

Description

hasDetailRows

Boolean

When false, report results are at summary level.

When true, report results are at the record detail level.

allData

Boolean

When True, all report results are returned.

When False, detailed data for the first 2000 report rows are returned.

reportMetadata

Report metadata

Information about the fields used to build the report.

factMap

Fact map

Collection of summary level data or both detailed and summary level data.

attributes

Attributes

Attributes for the instance of the report run.

reportExtendedMetadata Report extended

metadata

Information on report groupings, summary fields, and detailed data columns,

which is available if detailed data is requested.

groupingsDown

Groupings down

Collection of row groupings.

groupingsAcross

Groupings across

Collection of column groupings.

Attributes
Property

Type

Description

id

String

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

status

String

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.

ownerId

String

API name of the user that created the instance.

completionDate

Date, time string

Date, time when the instance of the report run finished. Only available if
the report instance ran successfully or couldnt be run because of an error.
Date-time information is in ISO-8601 format.

83

Reports API Resource Reference

Report List

Property

Type

Description

requestDate

Date, time string

Date and time when an instance of the report run was requested. Date-time
information is in ISO-8601 format.

type

String

Format of the resource.

reportId

String

Unique report ID.

reportName

String

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

Copy report

URL
/services/data/<latest API version>/analytics/reports

/services/data/<latest API version>/analytics/reports?cloneId=<report ID>

Formats
JSON

HTTP Methods
Method

Description

GET

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

POST

Makes a copy of a report. See this example.

84

Reports API Resource Reference

Report List

GET Response Body

Property

Type

Description

name

String

Report display name.

id

String

Unique report ID.

url

String

URL that returns report data.

describeUrl

String

URL that retrieves report metadata.

instancesUrl

String

Information for each instance of the report that was run asynchronously.

POST Response Body

Property

Type

Description

aggregates

Array of strings

Unique identities for summary or custom summary formula fields in

the report. For example:
a!Amount represents the average for the Amount column.
s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount
column.
x!Amount represents the maximum value of the Amount
column.
s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.

buckets

Bucket field

Describes a bucket field.

chart

Chart[]

Details about the chart used in a report.

crossFilters

Cross filter on page

69[]

Cross filters applied to the report.

customSummaryFormula

Custom summary
formula

Describes a custom summary formulas.

currency

String

Report currency, such as USD, EUR, GBP, for an organization that has
Multi-Currency enabled. Value is null if the organization does not
have Multi-Currency enabled.

detailColumns

Array of strings

Unique API names for the fields that have detailed data.

developerName

String

Report API name.

division

String

Determines the division of records to include in the report. For example,

West Coast and East Coast.

85

Reports API Resource Reference

Property

Report List

Type

Description
Available only if your organization uses divisions to segment data and
you have the Affected by Divisions permission. If you do not have the
Affected by Divisions permission, your reports include records in all
divisions.

folderId

String

ID of the folder that contains the report.

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.

groupingsAcross

Groupings across[]

Unique identities for each column grouping in a report. The identity is:
An empty array for reports in summary format as it cant have
column groupings.
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for a column
grouping.

groupingsDown

Groupings down[]

Unique identities for each row grouping in a report. The identity is:
BucketField_(ID) for bucket fields.
ID of a custom field when the custom field is used for grouping.

hasDetailRows

Boolean

Indicates whether to include detailed data with the summary data.

hasRecordCount

Boolean

Indicates whether the report shows the record count.

historicalSnapshotDates Array of strings

List of historical snapshot dates.

id

String

Unique report ID.

name

String

Display name of the report.

reportBooleanFilter

String

Logic to parse custom field filters. Value is null when filter logic is
not specified.
This is an example of a report filtered to show opportunities for accounts
that are either of customer or partner type OR their annual revenue
exceeds 100K AND they are medium or large sized businesses. The
filters are processed by the logic, (1 OR 2) AND 3.
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},

86

Reports API Resource Reference

Property

Report List

Type

Description
{
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}

reportFilters

Filter details[]

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

reportFormat

String

Format of the report. Value can be:

TABULAR
SUMMARY
MATRIX

reportType

Report type

Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
label: Of type string, this is the display name of the report type.

scope

String

Defines the scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities you own,
or opportunities your team owns. Valid values depend on the report
type.

showGrandTotal

Boolean

Indicates whether the report shows the grand total.

showSubtotals

Boolean

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

totals.

sortBy

String

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

standardDateFilter

Array of strings

Standard date filters available in reports. Each standard date filter

contains the following properties:
column: API name of the date field on which you filter the report data.
durationValue: The range for which you want to run the report.

The value is a date literal or 'CUSTOM.'

startDate: Start date.
endDate: End date.

87

Reports API Resource Reference

Report Error Codes

Property

Type

Description

standardFilters

Array of strings

List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.

topRows

Top rows

Describes a row limit filter applied to the report.

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:
HTTP
Response
Code

Error Message

400

The specified start date of <column name> specified for the standard date filter is invalid.

400

The specified end date of <column name> specified for the standard date filter is invalid.

400

The column <column name> specified for the standard date filter is invalid.

400

The column <column name> cannot be a standard date filter because it is not a date column.

400

The duration <value> specified for the standard date filter is invalid.

400

The report folder ID must be a valid folder ID.

400

The report folder ID can't be null.

400

The report name can't be null.

400

Column sorting isn't supported for matrix reports.

400

The sort column name must be from a selected column.

400

The sort column name can't be null.

400

A report can only be sorted by one column.

400

A snapshot date is not in the correct format. Accepted formats are one of the rolling dates defined or yyyy-MM-dd.

400

The request is invalid because reports that are not historical trending reports cannot have historical snapshot dates.

400

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.

400

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.

400

Cant run the report because it doesnt have any columns selected. Be sure to add fields as columns to the report
through the user interface.

400

The request is invalid because there are no filters. Specify filters or set filters as an empty array to omit them.

88

Reports API Resource Reference

Report Error Codes

HTTP
Response
Code

Error Message

400

The filter value for ID <value> is incorrect. Specify an ID that is 15 or 18 characters long, such as 006D000000CrRLw
or 005U0000000Rg2CIAS.

400

Specify a valid filterable column because <value> is invalid.

400

Specify a valid condition because <value> is invalid.

400

Filter the date in the correct format. Accepted formats are yyyy-MM-dd'T'HH:mm:ss'Z' and yyyy-MM-dd.

400

The date formula is too large. Specify a reasonable value.

400

The request is invalid because there is no metadata. Specify metadata in the request body.

400

The clone request must contain a valid cloneId parameter.

403

The report can't be deleted because there are one or more dashboards referencing it.

403

You don't have permission to create reports in the given folder.

403

You dont have permission to edit reports in the given folder.

403

The report definition is obsolete. Your administrator has disabled all reports for the custom object, or its relationships
have changed.

403

You dont have permission to run reports. Check that you have the Run Reports user permission.

403

You dont have sufficient privileges to perform this operation.

403

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.

403

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.

403

You can't run more than <number> reports synchronously every 60 minutes. Try again later.

404

Use a valid URL, for example, /services/data/(apiversion)/analytics/reports/(reportID)/describe, to retrieve report

metadata.

404

The data youre trying to access is unavailable.

415

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.

500

We ran into an error when fetching this reports metadata. Try to re-submit your query.

500

We ran into an error when running this report. Try to re-submit your query.

500

The request body is either invalid or incomplete.

500

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.

500

The report failed to be deleted.

500

The report failed to be created.

89

Reports API Resource Reference

Report Error Codes

HTTP
Response
Code

Error Message

500

The report failed to be saved.

501

Youre requesting data for an unsupported report format.

501

Historical trend data is unavailable in the report format requested. Change the report format to matrix and try again.

90

CHAPTER 5 Dashboards API Resource Reference

In this chapter ...

Dashboard List

Dashboard Results

Dashboard Status

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 Description
HTTP
Method

Dashboard List

GET

Returns a list of recently used dashboards.

POST

Makes a copy of a dashboard.

Dashboard Results GET

Returns the metadata, data, and status for the specified dashboard.

PUT

Triggers a dashboard refresh.

PATCH

Saves a dashboard.

DELETE

Deletes a dashboard.

Dashboard Status GET

Returns the status for the specified dashboard.

91

Dashboards API Resource Reference

Dashboard List

Dashboard List
Returns a list of recently used dashboards or clones a dashboard.

Syntax
URI
/vXX.X/analytics/dashboards

Formats
JSON
HTTP methods
Method

Description

GET

Returns a list of dashboards that were recently viewed by the API user. See this example.

POST

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

Type

Description

id

String

Unique identifier of the dashboard.

name

String

Localized display name of the dashboard.

statusUrl

String

Dashboard status URL.

url

String

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

92

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

Description

GET

Returns metadata, data, and status for the specified dashboard. See this example.

PUT

Triggers a dashboard refresh. See this example.

PATCH

Saves a dashboard. See this example.

DELETE

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

Description

runningUser

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.

filter1

Identifier of the selected filter option for the first filter. Gives an error if the filter option is
invalid.

filter2

Identifier of the selected filter option for the second filter. Gives an error if the filter option is
invalid.

filter3

Identifier of the selected filter option for the third filter. Gives an error if the filter option is
invalid.

GET and PUT Response body

Property

Type

Description

componentData

Component data[]

Ordered array containing data and status for each component of the dashboard.

dashboardMetadata Dashboard metadata

Metadata for the entire dashboard.

93

Dashboards API Resource Reference

Dashboard Results

Component data
Property

Type

Description

componentId

String

Unique identifier of the component.

reportResult

Report results

Report metadata and summary data for the dashboard component. Uses
the same data format as the Report API.

status

Component status

Queue and data status of the component.

Property

Type

Description

dataStatus

String

Status of the data set of the component. Value can be:

Component status

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

String

Unique identifier of error message. This property is only populated in case

of error.

errorMessage

String

Localized error message. This property is only populated in case of error.

errorSeverity

String

Severity of error code and message. Value can be:

Error
Warning
This property is only populated in case of error.

refreshDate

Date and time string

Date and time of last refresh in ISO-8601 format.

refreshStatus

String

Refresh status of the component. Value can be:

IDLE: The component is not currently being refreshed.
RUNNING: The component is currently being refreshed.

Dashboard metadata
Property

Type

Description

attributes

Attributes

Attributes for the dashboard resource, such as name, identifier, and

references to other related resources.

canChangeRunningUser Boolean

Indicates whether the user is allowed to select a specific running user.

Always true for team dashboards.

94

Dashboards API Resource Reference

Dashboard Results

Property

Type

Description

components

Component[]

Ordered array of components in this dashboard.

description

String

Dashboard description.

developerName

String

Unique API name of the dashboard.

filters

Filter[]

Ordered array of filters for this dashboard. The dashboard can have 0-3
filters.

folderId

String

ID of the folder that contains the dashboard.

id

String

Unique identifier of dashboard.

layout

Layout

Component layout for this dashboard.

name

String

Dashboard name.

runningUser

Running user

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.

Attributes
Property

Type

Description

dashboardId

String

Unique identifier of dashboard.

dashboardName

String

Dashboard name.

statusUrl

Url

The URL of the status resource for the dashboard.

type

String

This property is always set to Dashboard.

Property

Type

Description

componentData

Integer

Index into the component data array in the response body.

footer

String

Footer of the component.

header

String

Header of the component.

id

String

Unique identifier of the component.

properties

Properties (for Report

component type)

Component properties, including type-specific visualization properties.

Component

Properties (for Visualforce

page component type)
reportId

String

Unique identifier of the underlying report.

95

Dashboards API Resource Reference

Dashboard Results

Property

Type

Description

title

String

Title of the component

type

String

Type of the component. Value can be:

Report
VisualforcePage
If the component is an SControl, the value is not set.

Filter
Property

Type

Description

name

String

Localized display name of filter.

options

Filter option

Ordered array of possible filter options.

selectedOption

Integer

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.

Property

Type

Description

alias

String

Optional alias of the filter option.

id

String

Unique identifier of the filter option. Used as a value for the filter1,
filter2, and filter3 parameters.

operation

String

Unique API name for the filter operation. Valid filter operations depend on
the data type of the filter field. Value can be:

Filter option

equals
notEqual
lessThan
greaterThan
lessOrEqual
greaterOrEqual
contains
notContain
startsWith
includes
excludes
within
between

96

Dashboards API Resource Reference

Dashboard Results

Property

Type

Description

value

String

Value to filter on. Used for all operations except between.

startValue

String

Start value when using a between operation. Not set for all other
operations.

endValue

String

End value when using a between operation. Not set for all other operations.

Property

Type

Description

columns

Columns[]

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.

components

Components

Layout for dashboards. This property is available only if the dashboard was
created using Lightning Experience.

Property

Type

Description

components

Integer[]

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.

Property

Type

Description

colspan

Integer

Width of component in columns. For example, if colspan=3, then the

component spans 3 columns.

rowspan

Integer

Height of component in rows. For example, if rowspan=4, then the

component spans 4 rows.

column

String

Column position on the grid.

row

String

Row position on the grid.

Property

Type

Description

displayName

String

Display name of running user.

id

String

Unique identifier of running user.

Layout

Columns

Components

Running user

97

Dashboards API Resource Reference

Dashboard Results

Properties (for Report component type)

Property

Type

Description

aggregates

Array of strings

Unique identities for summary or custom summary formula fields in the

report. For example:
a!Amount represents the average for the Amount column.
s!Amount represents the sum of the Amount column.
m!Amount represents the minimum value of the Amount column.
x!Amount represents the maximum value of the Amount column.
s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is a
combination of the summary type and the field ID.

autoSelectColumns

Boolean

Indicates whether groupings and aggregates are automatically selected.

Valid values are true and false.

groupings

String

Report groupings included in the dashboard.

maxRows

Number

Maximum number of rows to be rendered, based on the sort value.

sort

Sort

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 Type-specific visualization properties.

(Chart)
Visualization properties
(Table)
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

98

Dashboards API Resource Reference

Dashboard Results

Visualization properties (Chart)

Property

Type

Description

axisRange

String

Range of values specified for the axis.

groupByType

String

Type of second-level grouping.

legendPosition

String

Position of legend on the grid. Valid values are bottom, right, and none.

showValues

Boolean

Indicates whether to include values in the chart. Valid values are true and
false.

Visualization properties (Table)

Property

Type

Description

breakPoints

Break point[]

Break points for the table component.

tableColumns

Table column[]

Columns of the table component.

Visualization properties (Metric)

Property

Type

Description

breakPoints

Break point[]

Break points for the metric component.

metricLabel

String

Label for the metric component.

Visualization properties (Gauge)

Property

Type

Description

breakPoints

Break point[]

Break points for the gauge component.

Property

Type

Description

column

String

Developer name for a sorted column.

sortOrder

String

Sort order. Value can be:

Sort

asc
desc

99

Dashboards API Resource Reference

Dashboard Results

Break point
Property

Type

Description

aggregateName

String

Aggregate column developer name that the break points have been applied
to.

breaks

Break[]

Break values for a break point.

Property

Type

Description

color

String

A hex value representing the color for the break point.

Break

Note: A color value of black displays only 1 character (0) instead of

6 characters (000000).
lowerBound

Number

Lower bound for the break point.

upperBound

Number

Upper bound for the break point.

Property

Type

Description

column

String

Developer name for the aggregate or grouping column.

isPercent

Boolean

Indicates whether the column value is shown as a percent.

scale

Number

The number of decimal places for the column value.

showTotal

Boolean

Indicates whether the column shows the total.

type

String

Type of the column. Value can be:

Table column

aggregate
grouping

Properties (for Visualforce page component type)

Property

Type

Description

pageName

String

Developer name of the Visualforce page.

height

String

Height of the Visualforce page, in pixels.

100

Dashboards API Resource Reference

Dashboard Status

PUT Response body

Property

Type

Description

statusUrl

String

URL of the status resource for the dashboard.

Dashboard Status
Returns the status for the specified dashboard.

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

Description

runningUser

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.

filter1

ID of the selected filter option for the first filter. Gives an error if the filter option is invalid.

filter2

ID of the selected filter option for the second filter. Gives an error if the filter option is invalid.

filter3

ID of the selected filter option for the third filter. Gives an error if the filter option is invalid.

Response body
Property

Type

Description

componentStatus

Component status with

id[]

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.

101

Dashboards API Resource Reference

Dashboard and Component Error Codes

Component status with id

Property

Type

Description

componentId

String

Unique ID of the dashboard component.

refreshDate

Date and time string

Date and time of last refresh in ISO-8601 format.

refreshStatus

String

Refresh status of the component. Value can be:

IDLE: The component is not currently being refreshed.
RUNNING: The component is currently being refreshed.

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:
HTTP
Response
Code

Error Message

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.

400

The running user for this dashboard is inactive. Your system administrator should select an active user for this
dashboard.

400

You don't have permission to view data as this user.

400

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.

400

The selected filter item isn't valid.

400

You can't refresh this dashboard. A refresh is already in progress.

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.

102

Dashboards API Resource Reference

Dashboard and Component Error Codes

errorCode

errorMessage

errorSeverity

201

This component must have a type and a data source.

Error

202

The source report isn't available; it's been deleted or isn't in a folder accessible to the dashboard's Error
running user.

203

This report can no longer be edited or run. Your administrator has disabled all reports for the
custom object, or its relationships have changed.

205

The source report is based on a report type that is inaccessible to the dashboard's running user. Error

208

Unable to run source report because its definition is invalid.

209

This report cannot be used as the source for this component. If it is a summary or matrix report, Error
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.

210

This row-limited tabular report cannot be used as the source for this component. Use the
Error
dashboard component editor to specify the data you want to display, or specify the Dashboard
Settings in the report.

211

To use this row-limited tabular report as the source, edit the report and specify the Name and Error
Value under Dashboard Settings. When updating the report, make sure you are the running user
of the dashboard.

212

Groupings and combination charts are not available for a row-limited tabular report. Set Group Error
By to None and deselect Plot Additional Values.

300

The results below may be incomplete because the underlying report produced too many summary Error
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.

301

Results may be incomplete because the source report had too many summary rows. Try filtering Warning
the report to reduce the number of rows returned.

302

The component can't be displayed because the source report exceeded the time limit.

Warning

303

The component can't be displayed because the source report failed to run.

Error

304

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.

Error

305

The component can't be displayed because the field(s) you chose for the filter are unavailable.

Error

308

You cant filter this component because data is in the joined report format. To filter the component, Error
change its report format.

309

The underlying report uses a snapshot date that is out of range.

103

Error

Error

Error

INDEX

Introduction 1

Resources (continued)
GET dashboard status 101
Get extended report metadata 57
Get recent reports list 84
GET report data 21, 71
GET report instance results 82
GET report instances 81
PATCH report 41
POST report data 21, 71
POST report instance 77, 81
run report asynchronously 77
Summary level results 21, 71

D
Dashboards API
filtering results 32
getting list of dashboards 28
getting results 28
getting status 33
refreshing 34
saving a dashboard 34

Reference
Dashboard error codes 102
Dashboard List 91
Dashboard Results 91
Dashboard Status 91
Report Describe 40
Report Execute 40
Report Instances 40
Report List 40
Reports and Dashboards REST API
report-level errors 88
Requirements and limitations 2
Resources
DELETE report 41
Detailed results 21, 71
Fact map 21
Filter report results 21, 71
Get basic report metadata 57
GET dashboard list 92
GET dashboard results 92

Salesforce Reports and Dashboards REST API

asynchronous 16
dashboard, clone 38
dashboard, delete 39
filter reports 16
GET request 4, 12, 16
list report runs 16
POST request 16
recently viewed 20
report data 4
report list 20
report metadata 12
report, clone 25
report, delete 26
report, save 23
synchronous 16

W
When to use Reports API 3
When to use the Dashboards API 27

104