Salesforce Reports And Dashboards REST API Developer Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 228 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Salesforce Reports and
Dashboards REST API
Developer Guide
Version 39.0, Spring ’17
@salesforcedocs
Last updated: March 10, 2017
© Copyright 2000–2017 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,
as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.
CONTENTS
Chapter 1: Salesforce Reports and Dashboards REST API .......................1
Requirements and Limitations .............................................2
Chapter 2: Examples: Reports REST API Resources ...........................3
Create a New Report ...................................................4
Run Reports Synchronously or Asynchronously .................................34
Get Report Metadata ..................................................42
Get a List of Report Types ................................................46
List Asynchronous Runs of a Report .........................................51
Filter Reports on Demand ...............................................52
List Recently Viewed Reports .............................................55
Decode the Fact Map ..................................................57
Get Report Data without Saving Changes to or Creating a Report .....................59
Save Changes to Reports ................................................71
Clone Reports .......................................................72
Delete Reports .......................................................73
Chapter 3: Examples: Dashboards REST API Resources .......................74
Get List of Recently Used Dashboards .......................................75
Get Dashboard Results .................................................75
Filter Dashboard Results ................................................79
Get Dashboard Status ..................................................80
Refresh a Dashboard ..................................................81
Save a Dashboard ....................................................81
Return Details About Dashboard Components .................................85
Get Dashboard Metadata ..............................................100
Clone a Dashboard ...................................................108
Delete a Dashboard ..................................................109
Chapter 4: Examples: Analytics Notifications REST API ........................110
Get Analytics Notifications ...............................................111
Create an Analytics Notification ...........................................113
Save Changes to an Analytics Notification ....................................114
Delete an Analytics Notification ...........................................115
Check Limits for Analytics Notifications ......................................115
Chapter 5: Reports API Resource Reference ...............................117
Report ............................................................118
Describe ..........................................................129
Execute Sync .......................................................143
Execute Async ......................................................150
Instances List .......................................................154
Instance Results .....................................................155
Report List .........................................................157
Query ............................................................161
Report Error Codes ...................................................172
Chapter 6: Report Types API Resource Reference ...........................175
Report Type List ......................................................176
Report Type ........................................................176
Chapter 7: Dashboards API Resource Reference ............................191
Dashboard List ......................................................192
Dashboard Results ...................................................192
Dashboard Describe .................................................202
Dashboard Status ...................................................207
Dashboard and Component Error Codes ....................................209
Chapter 8: Analytics Notifications API Resource Reference ....................211
Analytics Notification List ...............................................212
Analytics Notification ..................................................216
Analytics Notification Limits ..............................................221
INDEX ..........................................................223
Contents
CHAPTER 1 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
In this chapter ...
•Requirements and
Limitations web or mobile application, inside or outside the Salesforce platform. For example, you might use the
API to trigger a Chatter post with a snapshot of top-performing reps each quarter.
The Reports and Dashboards REST API will revolutionize the way you access and visualize your data. You
can:
•Integrate report data into custom objects.
•Define rich visualizations on top of the API to animate the data.
•Build custom dashboards.
•Automate reporting tasks.
At a high level, the API resources let you query and filter report data. You can:
•Run tabular, summary, or matrix reports synchronously or asynchronously.
•Filter for specific data on the fly.
•Query report metadata.
You can also work with dashboard resources to:
•Get a list of recently used dashboards.
•Get dashboard metadata and data.
•Query dashboard status.
•Refresh dashboards.
1
Requirements and Limitations
The Reports and Dashboards REST API is available for any organization that has API enabled. You must establish an authenticated session
using OAuth in order to access the Reports and Dashboards REST API. When working with this API, consider these restrictions in addition
to general API limits.
Note: Responses and requests are in JSON. While using the Reports and Dashboards REST API with a POST request body, you
must use content-type: application/json. You might get unexpected results if you don’t use this content type.
Reports Limits
•Cross filters, standard report filters, and filtering by row limit are unavailable when filtering data.
•Historical trend reports are only supported for matrix reports.
•The API can process only reports that contain up to 100 fields selected as columns.
•A list of up to 200 recently viewed reports can be returned.
•Your org can request up to 500 synchronous report runs per hour.
•The API supports up to 20 synchronous report run requests at a time.
•A list of up to 2,000 instances of a report that was run asynchronously can be returned.
•The API supports up to 200 requests at a time to get results of asynchronous report runs.
•Your organization can request up to 1,200 asynchronous requests per hour.
•Asynchronous report run results are available within a 24-hour rolling period.
•The API returns up to the first 2,000 report rows. You can narrow results using filters.
•You can add up to 20 custom field filters when you run a report.
Dashboards Limits
•Your org can request up to 200 dashboard refreshes per hour.
•Your org can request results for up to 5,000 dashboards per hour.
Analytics Notification Limits
•Each user can subscribe to up to 5 reports.
•Each user can create up to 5 Wave notifications.
Note: All limits that apply to reports created in the report builder also apply to the API, as do limits for dashboards created in the
dashboard builder. For more information, see “Salesforce Reports and Dashboards Limits” in the Salesforce online help.
2
Requirements and LimitationsSalesforce Reports and Dashboards REST API
CHAPTER 2 Examples: Reports REST API Resources
The Reports and Dashboards REST API is designed to let you query report data easily. Use the API to:
In this chapter ...
•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.
•Create a New Report
•Run Reports
Synchronously or
Asynchronously •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.
•Get Report Metadata
•Get a List of Report
Types
•List Asynchronous Runs of a Report.
Get a list of all instances of a report run asynchronously.
•List Asynchronous
Runs of a Report
•Filter Reports on
Demand •Filter Reports on Demand.
Get specific data back by running a report with filter changes in the metadata.
•List Recently Viewed
Reports •List Recently Viewed Reports
Get most recently viewed reports that you have permission to access.
•Decode the Fact Map
•Get Report Data
without Saving •Decode the Fact Map.
Get a visualized view of your report data.
Changes to or
Creating a Report
•Save Changes to Reports
Save changes to reports.
•Save Changes to
Reports
•Clone Reports •Clone Reports
Make copies of existing reports.
•Delete Reports
•Delete Reports
Clean up unused and obsolete reports.
3
Create a New Report
Create a new report using a POST request.
Example Usage
/services/data/v39.0/analytics/reports
Example Request Body
To create a report, you only have to specify reportMetadata with a name and a reportType to create a new report. Other
properties are optional.
{
"reportMetadata": {
"name":"NewReport",
"reportType": {
"type" : "Opportunity"
}
}
}
Example Response Body
The response includes the new report’s reportExtendedMetadata, reportMetadata, and reportTypeMetadata.
{
"reportExtendedMetadata" : {
"aggregateColumnInfo" : {
"RowCount" : {
"dataType" : "int",
"label" : "Record Count"
}
},
"detailColumnInfo" : {
"ROLLUP_DESCRIPTION" : {
"dataType" : "string",
"label" : "Owner Role"
},
"FULL_NAME" : {
"dataType" : "string",
"label" : "Opportunity Owner"
},
"ACCOUNT_NAME" : {
"dataType" : "string",
"label" : "Account Name"
},
"OPPORTUNITY_NAME" : {
"dataType" : "string",
"label" : "Opportunity Name"
},
"STAGE_NAME" : {
"dataType" : "picklist",
"label" : "Stage"
},
"FISCAL_QUARTER" : {
"dataType" : "string",
"label" : "Fiscal Period"
4
Create a New ReportExamples: Reports REST API Resources
},
"AMOUNT" : {
"dataType" : "currency",
"label" : "Amount"
},
"PROBABILITY" : {
"dataType" : "percent",
"label" : "Probability (%)"
},
"AGE" : {
"dataType" : "int",
"label" : "Age"
},
"CLOSE_DATE" : {
"dataType" : "date",
"label" : "Close Date"
},
"CREATED_DATE" : {
"dataType" : "datetime",
"label" : "Created Date"
},
"NEXT_STEP" : {
"dataType" : "string",
"label" : "Next Step"
},
"LEAD_SOURCE" : {
"dataType" : "picklist",
"label" : "Lead Source"
},
"TYPE" : {
"dataType" : "picklist",
"label" : "Type"
}
},
"groupingColumnInfo" : { }
},
"reportMetadata" : {
"aggregates" : [ "RowCount" ],
"chart" : null,
"crossFilters" : [ ],
"currency" : null,
"description" : null,
"detailColumns" : [ "ROLLUP_DESCRIPTION", "FULL_NAME", "ACCOUNT_NAME",
"OPPORTUNITY_NAME", "STAGE_NAME", "FISCAL_QUARTER", "AMOUNT", "PROBABILITY", "AGE",
"CLOSE_DATE", "CREATED_DATE", "NEXT_STEP", "LEAD_SOURCE", "TYPE" ],
"developerName" : "DocTest2_mG",
"division" : null,
"folderId" : "005R0000000Kg8cIAC",
"groupingsAcross" : [ ],
"groupingsDown" : [ ],
"hasDetailRows" : true,
"hasRecordCount" : true,
"historicalSnapshotDates" : [ ],
"id" : "00OR0000000PYkiMAG",
5
Create a New ReportExamples: Reports REST API Resources
"name" : "DocTest2",
"reportBooleanFilter" : null,
"reportFilters" : [ ],
"reportFormat" : "TABULAR",
"reportType" : {
"label" : "Opportunities",
"type" : "Opportunity"
},
"scope" : "organization",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CLOSE_DATE",
"durationValue" : "THIS_FISCAL_QUARTER",
"endDate" : "2016-12-31",
"startDate" : "2016-10-01"
},
"standardFilters" : [ {
"name" : "open",
"value" : "all"
}, {
"name" : "probability",
"value" : ">0"
} ],
"supportsRoleHierarchy" : true,
"userOrHierarchyFilterId" : null
},
"reportTypeMetadata" : {
"categories" : [ {
"columns" : {
"CREATED" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Created By"
},
"CREATED_ALIAS" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Created Alias"
},
"LAST_UPDATE_BY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Last Modified By"
},
"LAST_UPDATE_BY_ALIAS" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Last Modified Alias"
6
Create a New ReportExamples: Reports REST API Resources
},
"OPPORTUNITY_NAME" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Name"
},
"TYPE" : {
"dataType" : "picklist",
"filterValues" : [ {
"label" : "Existing Business",
"name" : "Existing Business"
}, {
"label" : "New Business",
"name" : "New Business"
} ],
"filterable" : true,
"label" : "Type"
},
"LEAD_SOURCE" : {
"dataType" : "picklist",
"filterValues" : [ {
"label" : "Advertisement",
"name" : "Advertisement"
}, {
"label" : "Employee Referral",
"name" : "Employee Referral"
}, {
"label" : "External Referral",
"name" : "External Referral"
}, {
"label" : "Partner",
"name" : "Partner"
}, {
"label" : "Public Relations",
"name" : "Public Relations"
}, {
"label" : "Seminar - Internal",
"name" : "Seminar - Internal"
}, {
"label" : "Seminar - Partner",
"name" : "Seminar - Partner"
}, {
"label" : "Trade Show",
"name" : "Trade Show"
}, {
"label" : "Web",
"name" : "Web"
}, {
"label" : "Word of mouth",
"name" : "Word of mouth"
}, {
"label" : "Other",
"name" : "Other"
7
Create a New ReportExamples: Reports REST API Resources
} ],
"filterable" : true,
"label" : "Lead Source"
},
"PARTNER_NAME" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Primary Partner"
},
"AMOUNT" : {
"dataType" : "currency",
"filterValues" : [ ],
"filterable" : true,
"label" : "Amount"
},
"CLOSED" : {
"dataType" : "boolean",
"filterValues" : [ {
"label" : "True",
"name" : "True"
}, {
"label" : "False",
"name" : "False"
} ],
"filterable" : true,
"label" : "Closed"
},
"WON" : {
"dataType" : "boolean",
"filterValues" : [ {
"label" : "True",
"name" : "True"
}, {
"label" : "False",
"name" : "False"
} ],
"filterable" : true,
"label" : "Won"
},
"CLOSE_DATE" : {
"dataType" : "date",
"filterValues" : [ ],
"filterable" : true,
"label" : "Close Date"
},
"CLOSE_DATE2" : {
"dataType" : "date",
"filterValues" : [ ],
"filterable" : true,
"label" : "Close Date (2)"
},
"CLOSE_MONTH" : {
"dataType" : "date",
8
Create a New ReportExamples: Reports REST API Resources
"filterValues" : [ ],
"filterable" : true,
"label" : "Close Month"
},
"LAST_STAGE_CHANGE_DATE" : {
"dataType" : "datetime",
"filterValues" : [ ],
"filterable" : true,
"label" : "Last Stage Change Date"
},
"NEXT_STEP" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Next Step"
},
"STAGE_NAME" : {
"dataType" : "picklist",
"filterValues" : [ {
"label" : "Prospecting",
"name" : "Prospecting"
}, {
"label" : "Qualification",
"name" : "Qualification"
}, {
"label" : "Needs Analysis",
"name" : "Needs Analysis"
}, {
"label" : "Value Proposition",
"name" : "Value Proposition"
}, {
"label" : "Id. Decision Makers",
"name" : "Id. Decision Makers"
}, {
"label" : "Perception Analysis",
"name" : "Perception Analysis"
}, {
"label" : "Proposal/Price Quote",
"name" : "Proposal/Price Quote"
}, {
"label" : "Negotiation/Review",
"name" : "Negotiation/Review"
}, {
"label" : "Closed Won",
"name" : "Closed Won"
}, {
"label" : "Closed Lost",
"name" : "Closed Lost"
} ],
"filterable" : true,
"label" : "Stage"
},
"PROBABILITY" : {
"dataType" : "percent",
9
Create a New ReportExamples: Reports REST API Resources
"filterValues" : [ ],
"filterable" : true,
"label" : "Probability (%)"
},
"FISCAL_QUARTER" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Fiscal Period"
},
"FISCAL_YEAR" : {
"dataType" : "int",
"filterValues" : [ ],
"filterable" : true,
"label" : "Fiscal Year"
},
"AGE" : {
"dataType" : "int",
"filterValues" : [ ],
"filterable" : true,
"label" : "Age"
},
"STAGE_DURATION" : {
"dataType" : "int",
"filterValues" : [ ],
"filterable" : true,
"label" : "Stage Duration"
},
"FORECAST_CATEGORY" : {
"dataType" : "picklist",
"filterValues" : [ {
"label" : "Omitted",
"name" : "Omitted"
}, {
"label" : "Pipeline",
"name" : "Pipeline"
}, {
"label" : "Best Case",
"name" : "Best Case"
}, {
"label" : "Commit",
"name" : "Commit"
}, {
"label" : "Closed",
"name" : "Closed"
} ],
"filterable" : true,
"label" : "Forecast Category"
},
"OPPORTUNITY_ID" : {
"dataType" : "id",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity ID"
10
Create a New ReportExamples: Reports REST API Resources
},
"LAST_ACTIVITY" : {
"dataType" : "date",
"filterValues" : [ ],
"filterable" : true,
"label" : "Last Activity"
},
"DESCRIPTION" : {
"dataType" : "textarea",
"filterValues" : [ ],
"filterable" : true,
"label" : "Description"
},
"HASOPPLINEITEM" : {
"dataType" : "boolean",
"filterValues" : [ {
"label" : "True",
"name" : "True"
}, {
"label" : "False",
"name" : "False"
} ],
"filterable" : true,
"label" : "Has Products"
},
"CREATED_DATE" : {
"dataType" : "datetime",
"filterValues" : [ ],
"filterable" : true,
"label" : "Created Date"
},
"LAST_UPDATE" : {
"dataType" : "datetime",
"filterValues" : [ ],
"filterable" : true,
"label" : "Last Modified Date"
}
},
"label" : "Opportunity Information"
}, {
"columns" : {
"FULL_NAME" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner"
},
"ROLLUP_DESCRIPTION" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Owner Role"
},
"ALIAS" : {
11
Create a New ReportExamples: Reports REST API Resources
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner Alias"
},
"OWNER_EMAIL" : {
"dataType" : "email",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner Email"
},
"OWNER_PHONE" : {
"dataType" : "phone",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Phone"
},
"OWNER_MOBILE_PHONE" : {
"dataType" : "phone",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Mobile Phone"
},
"OWNER_MANAGER" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Manager"
},
"OWNER_TITLE" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Title"
},
"OWNER_COMPANY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Company"
},
"OWNER_DEPARTMENT" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Department"
},
"OWNER_DIVISION" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Division"
},
"OWNER_PROFILE" : {
12
Create a New ReportExamples: Reports REST API Resources
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Opportunity Owner: Profile"
},
"OWNER_ACTIVE" : {
"dataType" : "boolean",
"filterValues" : [ {
"label" : "True",
"name" : "True"
}, {
"label" : "False",
"name" : "False"
} ],
"filterable" : true,
"label" : "Opportunity Owner: Active"
}
},
"label" : "Opportunity Owner Information"
}, {
"columns" : {
"ACCOUNT_NAME" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Account Name"
},
"ACCOUNT_OWNER" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Account Owner"
},
"ACCOUNT_OWNER_ALIAS" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Account Owner Alias"
},
"PARENT_NAME" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Parent Account"
},
"PARENT_ID" : {
"dataType" : "id",
"filterValues" : [ ],
"filterable" : true,
"label" : "Parent Account ID"
},
"SALES" : {
"dataType" : "currency",
"filterValues" : [ ],
13
Create a New ReportExamples: Reports REST API Resources
"filterable" : true,
"label" : "Annual Revenue"
},
"ACCOUNT_TYPE" : {
"dataType" : "picklist",
"filterValues" : [ {
"label" : "Analyst",
"name" : "Analyst"
}, {
"label" : "Competitor",
"name" : "Competitor"
}, {
"label" : "Customer",
"name" : "Customer"
}, {
"label" : "Integrator",
"name" : "Integrator"
}, {
"label" : "Investor",
"name" : "Investor"
}, {
"label" : "Partner",
"name" : "Partner"
}, {
"label" : "Press",
"name" : "Press"
}, {
"label" : "Prospect",
"name" : "Prospect"
}, {
"label" : "Reseller",
"name" : "Reseller"
}, {
"label" : "Other",
"name" : "Other"
} ],
"filterable" : true,
"label" : "Account Type"
},
"INDUSTRY" : {
"dataType" : "picklist",
"filterValues" : [ {
"label" : "Agriculture",
"name" : "Agriculture"
}, {
"label" : "Apparel",
"name" : "Apparel"
}, {
"label" : "Banking",
"name" : "Banking"
}, {
"label" : "Biotechnology",
"name" : "Biotechnology"
}, {
14
Create a New ReportExamples: Reports REST API Resources
"label" : "Chemicals",
"name" : "Chemicals"
}, {
"label" : "Communications",
"name" : "Communications"
}, {
"label" : "Construction",
"name" : "Construction"
}, {
"label" : "Consulting",
"name" : "Consulting"
}, {
"label" : "Education",
"name" : "Education"
}, {
"label" : "Electronics",
"name" : "Electronics"
}, {
"label" : "Energy",
"name" : "Energy"
}, {
"label" : "Engineering",
"name" : "Engineering"
}, {
"label" : "Entertainment",
"name" : "Entertainment"
}, {
"label" : "Environmental",
"name" : "Environmental"
}, {
"label" : "Finance",
"name" : "Finance"
}, {
"label" : "Food & Beverage",
"name" : "Food & Beverage"
}, {
"label" : "Government",
"name" : "Government"
}, {
"label" : "Healthcare",
"name" : "Healthcare"
}, {
"label" : "Hospitality",
"name" : "Hospitality"
}, {
"label" : "Insurance",
"name" : "Insurance"
}, {
"label" : "Machinery",
"name" : "Machinery"
}, {
"label" : "Manufacturing",
"name" : "Manufacturing"
}, {
15
Create a New ReportExamples: Reports REST API Resources
"label" : "Media",
"name" : "Media"
}, {
"label" : "Not For Profit",
"name" : "Not For Profit"
}, {
"label" : "Other",
"name" : "Other"
}, {
"label" : "Recreation",
"name" : "Recreation"
}, {
"label" : "Retail",
"name" : "Retail"
}, {
"label" : "Shipping",
"name" : "Shipping"
}, {
"label" : "Technology",
"name" : "Technology"
}, {
"label" : "Telecommunications",
"name" : "Telecommunications"
}, {
"label" : "Transportation",
"name" : "Transportation"
}, {
"label" : "Utilities",
"name" : "Utilities"
} ],
"filterable" : true,
"label" : "Industry"
},
"EMPLOYEES" : {
"dataType" : "int",
"filterValues" : [ ],
"filterable" : true,
"label" : "Employees"
},
"ACCOUNT_ID" : {
"dataType" : "id",
"filterValues" : [ ],
"filterable" : true,
"label" : "Account ID"
},
"ACCOUNT_LAST_ACTIVITY" : {
"dataType" : "date",
"filterValues" : [ ],
"filterable" : true,
"label" : "Account: Last Activity"
},
"ACCOUNT_CREATED_DATE" : {
"dataType" : "datetime",
"filterValues" : [ ],
16
Create a New ReportExamples: Reports REST API Resources
"filterable" : true,
"label" : "Account: Created Date"
},
"ACCOUNT_LAST_UPDATE" : {
"dataType" : "datetime",
"filterValues" : [ ],
"filterable" : true,
"label" : "Account: Last Modified Date"
},
"ACCOUNT_DESCRIPTION" : {
"dataType" : "textarea",
"filterValues" : [ ],
"filterable" : true,
"label" : "Account Description"
}
},
"label" : "Account: General"
}, {
"columns" : {
"ADDRESS1_STREET" : {
"dataType" : "textarea",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing Street"
},
"ADDRESS1_LINE1" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing Address Line 1"
},
"ADDRESS1_LINE2" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing Address Line 2"
},
"ADDRESS1_LINE3" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing Address Line 3"
},
"ADDRESS1_CITY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing City"
},
"ADDRESS1_STATE" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing State/Province"
17
Create a New ReportExamples: Reports REST API Resources
},
"ADDRESS1_ZIP" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing Zip/Postal Code"
},
"ADDRESS1_COUNTRY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Billing Country"
},
"ADDRESS2_STREET" : {
"dataType" : "textarea",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping Street"
},
"ADDRESS2_LINE1" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping Address Line 1"
},
"ADDRESS2_LINE2" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping Address Line 2"
},
"ADDRESS2_LINE3" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping Address Line 3"
},
"ADDRESS2_CITY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping City"
},
"ADDRESS2_STATE" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping State/Province"
},
"ADDRESS2_ZIP" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping Zip/Postal Code"
18
Create a New ReportExamples: Reports REST API Resources
},
"ADDRESS2_COUNTRY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Shipping Country"
}
},
"label" : "Account: Address"
}, {
"columns" : {
"PHONE1" : {
"dataType" : "phone",
"filterValues" : [ ],
"filterable" : true,
"label" : "Phone"
},
"PHONE2" : {
"dataType" : "phone",
"filterValues" : [ ],
"filterable" : true,
"label" : "Fax"
},
"URL" : {
"dataType" : "url",
"filterValues" : [ ],
"filterable" : true,
"label" : "Website"
}
},
"label" : "Account: Ph/Fax"
}, {
"columns" : {
"CONTACT" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Primary Contact"
},
"CON.TITLE" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Contact: Title"
},
"CON.PHONE" : {
"dataType" : "phone",
"filterValues" : [ ],
"filterable" : true,
"label" : "Contact: Phone"
},
"CON.EMAIL" : {
"dataType" : "email",
"filterValues" : [ ],
19
Create a New ReportExamples: Reports REST API Resources
"filterable" : true,
"label" : "Contact: Email"
}
},
"label" : "Primary Contact"
}, {
"columns" : {
"CON.ADDRESS2_STREET" : {
"dataType" : "textarea",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing Street"
},
"CON.ADDRESS2_LINE1" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing Address Line 1"
},
"CON.ADDRESS2_LINE2" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing Address Line 2"
},
"CON.ADDRESS2_LINE3" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing Address Line 3"
},
"CON.ADDRESS2_CITY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing City"
},
"CON.ADDRESS2_STATE" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing State/Province"
},
"CON.ADDRESS2_ZIP" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing Zip/Postal Code"
},
"CON.ADDRESS2_COUNTRY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Mailing Country"
20
Create a New ReportExamples: Reports REST API Resources
},
"CON.ADDRESS1_STREET" : {
"dataType" : "textarea",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other Street"
},
"CON.ADDRESS1_LINE1" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other Address Line 1"
},
"CON.ADDRESS1_LINE2" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other Address Line 2"
},
"CON.ADDRESS1_LINE3" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other Address Line 3"
},
"CON.ADDRESS1_CITY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other City"
},
"CON.ADDRESS1_STATE" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other State/Province"
},
"CON.ADDRESS1_ZIP" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other Zip/Postal Code"
},
"CON.ADDRESS1_COUNTRY" : {
"dataType" : "string",
"filterValues" : [ ],
"filterable" : true,
"label" : "Other Country"
}
},
"label" : "Contact: Address"
} ],
"dataTypeFilterOperatorMap" : {
"date" : [ {
21
Create a New ReportExamples: Reports REST API Resources
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
} ],
"string" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
}, {
"label" : "contains",
"name" : "contains"
}, {
"label" : "does not contain",
"name" : "notContain"
}, {
"label" : "starts with",
"name" : "startsWith"
} ],
"picklist" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
22
Create a New ReportExamples: Reports REST API Resources
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
}, {
"label" : "contains",
"name" : "contains"
}, {
"label" : "does not contain",
"name" : "notContain"
}, {
"label" : "starts with",
"name" : "startsWith"
} ],
"textarea" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
}, {
"label" : "contains",
"name" : "contains"
}, {
"label" : "does not contain",
"name" : "notContain"
}, {
"label" : "starts with",
"name" : "startsWith"
} ],
"percent" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
23
Create a New ReportExamples: Reports REST API Resources
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
} ],
"int" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
} ],
"url" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
}, {
"label" : "contains",
"name" : "contains"
}, {
24
Create a New ReportExamples: Reports REST API Resources
"label" : "does not contain",
"name" : "notContain"
}, {
"label" : "starts with",
"name" : "startsWith"
} ],
"datetime" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
} ],
"boolean" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
} ],
"phone" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
}, {
"label" : "contains",
"name" : "contains"
}, {
25
Create a New ReportExamples: Reports REST API Resources
"label" : "does not contain",
"name" : "notContain"
}, {
"label" : "starts with",
"name" : "startsWith"
} ],
"currency" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
} ],
"id" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "starts with",
"name" : "startsWith"
} ],
"email" : [ {
"label" : "equals",
"name" : "equals"
}, {
"label" : "not equal to",
"name" : "notEqual"
}, {
"label" : "less than",
"name" : "lessThan"
}, {
"label" : "greater than",
"name" : "greaterThan"
}, {
"label" : "less or equal",
"name" : "lessOrEqual"
}, {
"label" : "greater or equal",
"name" : "greaterOrEqual"
}, {
26
Create a New ReportExamples: Reports REST API Resources
"label" : "contains",
"name" : "contains"
}, {
"label" : "does not contain",
"name" : "notContain"
}, {
"label" : "starts with",
"name" : "startsWith"
} ]
},
"divisionInfo" : null,
"scopeInfo" : {
"defaultValue" : "organization",
"values" : [ {
"allowsDivision" : false,
"label" : "My opportunities",
"value" : "user"
}, {
"allowsDivision" : false,
"label" : "My team's opportunities",
"value" : "team"
}, {
"allowsDivision" : true,
"label" : "All opportunities",
"value" : "organization"
} ]
},
"standardDateFilterDurationGroups" : [ {
"label" : "",
"standardDateFilterDurations" : [ {
"endDate" : "2016-12-12",
"label" : "Custom",
"startDate" : "2016-12-13",
"value" : "CUSTOM"
} ]
}, {
"label" : "Fiscal Year",
"standardDateFilterDurations" : [ {
"endDate" : "2016-12-31",
"label" : "Current FY",
"startDate" : "2016-01-01",
"value" : "THIS_FISCAL_YEAR"
}, {
"endDate" : "2015-12-31",
"label" : "Previous FY",
"startDate" : "2015-01-01",
"value" : "LAST_FISCAL_YEAR"
}, {
"endDate" : "2015-12-31",
"label" : "Previous 2 FY",
"startDate" : "2014-01-01",
"value" : "LAST_N_FISCAL_YEARS:2"
}, {
"endDate" : "2014-12-31",
27
Create a New ReportExamples: Reports REST API Resources
"label" : "2 FY Ago",
"startDate" : "2014-01-01",
"value" : "LAST_N_FISCAL_YEARS_AGO:2"
}, {
"endDate" : "2017-12-31",
"label" : "Next FY",
"startDate" : "2017-01-01",
"value" : "NEXT_FISCAL_YEAR"
}, {
"endDate" : "2016-12-31",
"label" : "Current and Previous FY",
"startDate" : "2015-01-01",
"value" : "THIS_AND_LAST_FISCAL_YEAR:2"
}, {
"endDate" : "2016-12-31",
"label" : "Current and Previous 2 FY",
"startDate" : "2014-01-01",
"value" : "THIS_AND_LAST_N_FISCAL_YEARS:2"
}, {
"endDate" : "2017-12-31",
"label" : "Current and Next FY",
"startDate" : "2016-01-01",
"value" : "THIS_AND_NEXT_FISCAL_YEAR"
} ]
}, {
"label" : "Fiscal Quarter",
"standardDateFilterDurations" : [ {
"endDate" : "2016-12-31",
"label" : "Current FQ",
"startDate" : "2016-10-01",
"value" : "THIS_FISCAL_QUARTER"
}, {
"endDate" : "2017-03-31",
"label" : "Current and Next FQ",
"startDate" : "2016-10-01",
"value" : "THIS_AND_NEXT_FISCAL_QUARTER"
}, {
"endDate" : "2016-12-31",
"label" : "Current and Previous FQ",
"startDate" : "2016-07-01",
"value" : "LAST_AND_THIS_FISCAL_QUARTER"
}, {
"endDate" : "2017-03-31",
"label" : "Next FQ",
"startDate" : "2017-01-01",
"value" : "NEXT_FISCAL_QUARTER"
}, {
"endDate" : "2016-09-30",
"label" : "Previous FQ",
"startDate" : "2016-07-01",
"value" : "LAST_FISCAL_QUARTER"
}, {
"endDate" : "2017-09-30",
"label" : "Current and Next 3 FQ",
28
Create a New ReportExamples: Reports REST API Resources
"startDate" : "2016-10-01",
"value" : "THIS_AND_NEXT_N_FISCAL_QUARTERS:3"
} ]
}, {
"label" : "Calendar Year",
"standardDateFilterDurations" : [ {
"endDate" : "2016-12-31",
"label" : "Current CY",
"startDate" : "2016-01-01",
"value" : "THIS_YEAR"
}, {
"endDate" : "2015-12-31",
"label" : "Previous CY",
"startDate" : "2015-01-01",
"value" : "LAST_YEAR"
}, {
"endDate" : "2015-12-31",
"label" : "Previous 2 CY",
"startDate" : "2014-01-01",
"value" : "LAST_N_YEARS:2"
}, {
"endDate" : "2014-12-31",
"label" : "2 CY Ago",
"startDate" : "2014-01-01",
"value" : "LAST_N_YEARS_AGO:2"
}, {
"endDate" : "2017-12-31",
"label" : "Next CY",
"startDate" : "2017-01-01",
"value" : "NEXT_YEAR"
}, {
"endDate" : "2016-12-31",
"label" : "Current and Previous CY",
"startDate" : "2015-01-01",
"value" : "THIS_AND_LAST_YEAR:2"
}, {
"endDate" : "2016-12-31",
"label" : "Current and Previous 2 CY",
"startDate" : "2014-01-01",
"value" : "THIS_AND_LAST_N_YEARS:2"
}, {
"endDate" : "2017-12-31",
"label" : "Current and Next CY",
"startDate" : "2016-01-01",
"value" : "THIS_AND_NEXT_YEAR"
} ]
}, {
"label" : "Calendar Quarter",
"standardDateFilterDurations" : [ {
"endDate" : "2016-12-31",
"label" : "Current CQ",
"startDate" : "2016-10-01",
"value" : "THIS_QUARTER"
}, {
29
Create a New ReportExamples: Reports REST API Resources
"endDate" : "2017-03-31",
"label" : "Current and Next CQ",
"startDate" : "2016-10-01",
"value" : "THIS_AND_NEXT_QUARTER"
}, {
"endDate" : "2016-12-31",
"label" : "Current and Previous CQ",
"startDate" : "2016-07-01",
"value" : "LAST_AND_THIS_QUARTER"
}, {
"endDate" : "2017-03-31",
"label" : "Next CQ",
"startDate" : "2017-01-01",
"value" : "NEXT_QUARTER"
}, {
"endDate" : "2016-09-30",
"label" : "Previous CQ",
"startDate" : "2016-07-01",
"value" : "LAST_QUARTER"
}, {
"endDate" : "2017-09-30",
"label" : "Current and Next 3 CQ",
"startDate" : "2016-10-01",
"value" : "THIS_AND_NEXT_N_QUARTERS:3"
} ]
}, {
"label" : "Calendar Month",
"standardDateFilterDurations" : [ {
"endDate" : "2016-11-30",
"label" : "Last Month",
"startDate" : "2016-11-01",
"value" : "LAST_MONTH"
}, {
"endDate" : "2016-12-31",
"label" : "This Month",
"startDate" : "2016-12-01",
"value" : "THIS_MONTH"
}, {
"endDate" : "2017-01-31",
"label" : "Next Month",
"startDate" : "2017-01-01",
"value" : "NEXT_MONTH"
}, {
"endDate" : "2016-12-31",
"label" : "Current and Previous Month",
"startDate" : "2016-11-01",
"value" : "LAST_AND_THIS_MONTH"
}, {
"endDate" : "2017-01-31",
"label" : "Current and Next Month",
"startDate" : "2016-12-01",
"value" : "THIS_AND_NEXT_MONTH"
} ]
}, {
30
Create a New ReportExamples: Reports REST API Resources
"label" : "Calendar Week",
"standardDateFilterDurations" : [ {
"endDate" : "2016-12-10",
"label" : "Last Week",
"startDate" : "2016-12-04",
"value" : "LAST_WEEK"
}, {
"endDate" : "2016-12-17",
"label" : "This Week",
"startDate" : "2016-12-11",
"value" : "THIS_WEEK"
}, {
"endDate" : "2016-12-24",
"label" : "Next Week",
"startDate" : "2016-12-18",
"value" : "NEXT_WEEK"
} ]
}, {
"label" : "Day",
"standardDateFilterDurations" : [ {
"endDate" : "2016-12-12",
"label" : "Yesterday",
"startDate" : "2016-12-12",
"value" : "YESTERDAY"
}, {
"endDate" : "2016-12-13",
"label" : "Today",
"startDate" : "2016-12-13",
"value" : "TODAY"
}, {
"endDate" : "2016-12-14",
"label" : "Tomorrow",
"startDate" : "2016-12-14",
"value" : "TOMORROW"
}, {
"endDate" : "2016-12-13",
"label" : "Last 7 Days",
"startDate" : "2016-12-07",
"value" : "LAST_N_DAYS:7"
}, {
"endDate" : "2016-12-13",
"label" : "Last 30 Days",
"startDate" : "2016-11-14",
"value" : "LAST_N_DAYS:30"
}, {
"endDate" : "2016-12-13",
"label" : "Last 60 Days",
"startDate" : "2016-10-15",
"value" : "LAST_N_DAYS:60"
}, {
"endDate" : "2016-12-13",
"label" : "Last 90 Days",
"startDate" : "2016-09-15",
"value" : "LAST_N_DAYS:90"
31
Create a New ReportExamples: Reports REST API Resources
}, {
"endDate" : "2016-12-13",
"label" : "Last 120 Days",
"startDate" : "2016-08-16",
"value" : "LAST_N_DAYS:120"
}, {
"endDate" : "2016-12-19",
"label" : "Next 7 Days",
"startDate" : "2016-12-13",
"value" : "NEXT_N_DAYS:7"
}, {
"endDate" : "2017-01-11",
"label" : "Next 30 Days",
"startDate" : "2016-12-13",
"value" : "NEXT_N_DAYS:30"
}, {
"endDate" : "2017-02-10",
"label" : "Next 60 Days",
"startDate" : "2016-12-13",
"value" : "NEXT_N_DAYS:60"
}, {
"endDate" : "2017-03-12",
"label" : "Next 90 Days",
"startDate" : "2016-12-13",
"value" : "NEXT_N_DAYS:90"
}, {
"endDate" : "2017-04-11",
"label" : "Next 120 Days",
"startDate" : "2016-12-13",
"value" : "NEXT_N_DAYS:120"
} ]
} ],
"standardFilterInfos" : {
"probability" : {
"type" : "PICKLIST",
"filterValues" : [ {
"label" : "All",
"name" : ">0"
}, {
"label" : "> 90%",
"name" : "gt90"
}, {
"label" : "> 80%",
"name" : "gt80"
}, {
"label" : "> 70%",
"name" : "gt70"
}, {
"label" : "> 60%",
"name" : "gt60"
}, {
"label" : "> 50%",
"name" : "gt50"
}, {
32
Create a New ReportExamples: Reports REST API Resources
"label" : "> 40%",
"name" : "gt40"
}, {
"label" : "> 30%",
"name" : "gt30"
}, {
"label" : "> 20%",
"name" : "gt20"
}, {
"label" : "> 10%",
"name" : "gt10"
}, {
"label" : "< 90%",
"name" : "lt90"
}, {
"label" : "< 80%",
"name" : "lt80"
}, {
"label" : "< 70%",
"name" : "lt70"
}, {
"label" : "< 60%",
"name" : "lt60"
}, {
"label" : "< 50%",
"name" : "lt50"
}, {
"label" : "< 40%",
"name" : "lt40"
}, {
"label" : "< 30%",
"name" : "lt30"
}, {
"label" : "< 20%",
"name" : "lt20"
}, {
"label" : "< 10%",
"name" : "lt10"
} ],
"label" : "Probability"
},
"open" : {
"type" : "PICKLIST",
"filterValues" : [ {
"label" : "Any",
"name" : "all"
}, {
"label" : "Open",
"name" : "open"
}, {
"label" : "Closed",
"name" : "closed"
}, {
"label" : "Closed Won",
33
Create a New ReportExamples: Reports REST API Resources
"name" : "closedwon"
} ],
"label" : "Opportunity Status"
}
}
}
}
Run Reports Synchronously or Asynchronously
Get summary data with or without details by running a report synchronously or asynchronously through the API. When you run a report,
the API returns data for the same number of records that are available when the report is run in the Salesforce user interface.
Run a report synchronously if you expect it to finish running quickly. Otherwise, we recommend that you run reports through the API
asynchronously for these reasons:
•Long running reports have a lower risk of reaching the timeout limit when run asynchronously.
•The 2-minute overall Salesforce API timeout limit doesn’t apply to asynchronous runs.
•The Salesforce Reports and Dashboards REST API can handle a higher number of asynchronous run requests at a time.
•Since the results of an asynchronously run report are stored for a 24-hr rolling period, they’re available for recurring access.
To run a report synchronously:
•Send a GET or POST request to the Execute Sync resource to get data.
•Use a POST request to get specific results on the fly by passing dynamic filters, groupings, and aggregates in the report metadata.
To fetch report data asynchronously:
1. Send a POST request to the Execute Async resource. If you’re passing filters, include them in the POST request metadata. The request
returns the instance ID where results of the run are stored.
2. Send a GET request to the Instance Results resource to fetch data using the instance ID.
Example of a synchronous report run
This GET request to the Execute Sync resource,
/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK?includeDetails=true, for a synchronous
run returns summary data with details.
{
"attributes" : {
"describeUrl" :
"/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/describe",
"instancesUrl" :
"/services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances",
"reportId" :
"00OR0000000K2UeMAK",
"reportName" : "Deals Closing This Quarter",
"type" : "Report"
},
"allData" : true,
"factMap" : {
"2!0_0" : {
34
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
"aggregates" : [
{ "label" : "$16,000.01", "value" : 16000.010000000000218278728425502777099609375
},
{ "label" : "$16,000.01", "value" : 16000.010000000000218278728425502777099609375
},
{ "label" : "1", "value" : 1 } ],
"rows" : [ {
"dataCells" : [
{ "label" : "Acme - 200 Widgets", "value" : "006R00000023IDYIA2" },
{ "label" : "$16,000.01",
"value" : { "amount" : 16000.01, "currency" : null } },
{ "label" : "Word of mouth", "value" : "Word of mouth" },
{ "label" : "Need estimate", "value" : "Need estimate" },
{ "label" : "60%", "value" : 60},
{ "label" : "Q3-2015", "value" : "Q3-2015" },
{ "label" : "12", "value" : 12 },
{ "label" : "7/31/2015", "value" : "2015-07-31" },
{ "label" : "Fred Wiliamson", "value" : "005R0000000Hv5rIAC" },
{ "label" : "-", "value" : null } ]
} ]
},
"T!0" : {
"aggregates" : [
{ "label" : "$32,021.01", "value" : 32021.00999999999839928932487964630126953125
},
{ "label" : "$16,010.51", "value" : 16010.504999999999199644662439823150634765625
},
{ "label" : "2", "value" : 2 } ],
"rows" : [ ]
},
...
"T!T" : {
"aggregates" : [
{ "label" : "$153,042.01", "value" : 153042.01000000000931322574615478515625 },
{ "label" : "$25,507.00", "value" : 25507.00166666666700621135532855987548828125
},
{ "label" : "6", "value" : 6 } ],
"rows" : [ ]
},
...
"groupingsAcross" : {
"groupings" : [
{
"groupings" : [
{ "groupings" : [ ], "key" : "0_0", "label" : "Existing Business", "value" :
"Existing Business" } ],
"key" : "0",
"label" : "July 2015",
"value" : "2015-07-01"
},
{
"groupings" : [
{ "groupings" : [ ], "key" : "1_0", "label" : "Existing Business", "value" :
"Existing Business" },
35
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
{ "groupings" : [ ], "key" : "1_1", "label" : "New Business", "value" : "New
Business" } ],
"key" : "1",
"label" : "August 2015",
"value" : "2015-08-01"
},
{
"groupings" : [
{ "groupings" : [ ], "key" : "2_0", "label" : "Existing Business", "value" :
"Existing Business" } ],
"key" : "2",
"label" : "September 2015",
"value" : "2015-09-01"
}
]
},
"groupingsDown" : {
"groupings" : [
{ "groupings" : [ ], "key" : "0", "label" : "Acme", "value" : "001R0000002GuzsIAC"
},
{ "groupings" : [ ], "key" : "1", "label" : "Facebook", "value" : "001R0000001nUAmIAM"
},
{ "groupings" : [ ], "key" : "2", "label" : "Home Depot", "value" :
"001R0000002Gv5zIAC" },
{ "groupings" : [ ], "key" : "3", "label" : "Mircosoft", "value" : "001R0000002Gv5QIAS"
} ]
},
"hasDetailRows" : true,
"reportExtendedMetadata" : {
"aggregateColumnInfo" : {
"s!AMOUNT" : {
"acrossGroupingContext" : null,
"dataType" : "currency",
"downGroupingContext" : null,
"label" : "Sum of Amount" },
"a!AMOUNT" : {
"acrossGroupingContext" : null,
"dataType" : "currency",
"downGroupingContext" : null,
"label" : "Average Amount" },
"RowCount" : {
"acrossGroupingContext" : null,
"dataType" : "int",
"downGroupingContext" : null,
"label" : "Record Count" }
},
"detailColumnInfo" : {
"OPPORTUNITY_NAME" : { "dataType" : "string", "label" : "Opportunity Name" },
"AMOUNT" : { "dataType" : "currency", "label" : "Amount" },
"LEAD_SOURCE" : { "dataType" : "picklist", "label" : "Lead Source" },
"NEXT_STEP" : { "dataType" : "string", "label" : "Next Step" },
"PROBABILITY" : { "dataType" : "percent", "label" : "Probability (%)" },
"FISCAL_QUARTER" : { "dataType" : "string", "label" : "Fiscal Period" },
36
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
"AGE" : { "dataType" : "int", "label" : "Age" },
"CREATED_DATE" : { "dataType" : "datetime", "label" : "Created Date" },
"FULL_NAME" : { "dataType" : "string", "label" : "Opportunity Owner" },
"ROLLUP_DESCRIPTION" : { "dataType" : "string", "label" : "Owner Role" }
},
"groupingColumnInfo" : {
"ACCOUNT_NAME" : { "dataType" : "string", "groupingLevel" : 0, "label" : "Account
Name" },
"CLOSE_DATE" : { "dataType" : "date", "groupingLevel" : 0, "label" : "Close Date"
},
"TYPE" : { "dataType" : "picklist", "groupingLevel" : 1, "label" : "Type" }
}
},
"reportMetadata" : {
"aggregates" : [ "s!AMOUNT", "a!AMOUNT", "RowCount" ],
"chart" : {
"chartType" : "Donut",
"groupings" : [ "CLOSE_DATE" ],
"hasLegend" : true,
"showChartValues" : false,
"summaries" : [ "s!AMOUNT" ],
"summaryAxisLocations" : [ "Y" ],
"title" : "Pipeline by Stage and Type"
},
"currency" : null,
"description" : null,
"detailColumns" : [ "OPPORTUNITY_NAME", "AMOUNT", "LEAD_SOURCE","NEXT_STEP",
"PROBABILITY", "FISCAL_QUARTER", "AGE", "CREATED_DATE", "FULL_NAME",
"ROLLUP_DESCRIPTION" ],
"developerName" : "Deals_Closing_This_Quarter",
"division" : null,
"folderId" : "00lR0000000M8IiIAK",
"groupingsAcross" : [
{ "dateGranularity" : "Month", "name" : "CLOSE_DATE", "sortAggregate" : null,
"sortOrder" : "Asc"},
{ "dateGranularity" : "None", "name" : "TYPE", "sortAggregate" : null, "sortOrder"
: "Asc" } ],
"groupingsDown" : [
{ "dateGranularity" : "None", "name" : "ACCOUNT_NAME", "sortAggregate" : null,
"sortOrder" : "Asc" } ],
"hasDetailRows" : true,
"hasRecordCount" : true,
"historicalSnapshotDates" : [ ],
"id" : "00OR0000000K2UeMAK",
"name" : "Deals Closing This Quarter",
"reportBooleanFilter" : null,
"reportFilters" : [
{ "column" : "BucketField_36625466", "isRunPageEditable" : true, "operator" : "equals",
"value" : "Early,Late" },
{ "column" : "TYPE", "isRunPageEditable" : true, "operator" : "equals", "value" :
"Existing Business,New Business" } ],
"reportFormat" : "MATRIX",
"reportType" : { "label" : "Opportunities", "type" : "Opportunity" },
"scope" : "organization",
37
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CLOSE_DATE",
"durationValue" : "THIS_FISCAL_QUARTER",
"endDate" : "2015-09-30",
"startDate" : "2015-07-01" },
"standardFilters" : [
{ "name" : "open", "value" : "all" },
{ "name" : "probability", "value" : ">0" } ]
}
}
Example of an asynchronous report run
1. This is a POST request, /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" } ],
38
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
"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",
"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" : {
39
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
"completionDate" : "2015-08-12T16:05:44Z",
"id" : "0LGR00000000He3OAE",
"ownerId" : "005R0000000Hv5rIAC",
"queryable" : false,
"reportId" : "00OR0000000K2UeMAK",
"reportName" : "Deals Closing This Quarter",
"requestDate" : "2015-08-12T16:05:43Z",
"status" : "Success",
"type" : "ReportInstance" },
"allData" : true,
"factMap" : {
"2!0_0" : {
"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" : {
40
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
"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"
},
"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"
41
Run Reports Synchronously or AsynchronouslyExamples: Reports REST API Resources
: "Asc" } ],
"groupingsDown" : [
{ "dateGranularity" : "None", "name" : "ACCOUNT_NAME", "sortAggregate" : null,
"sortOrder" : "Asc" } ],
"hasDetailRows" : true,
"hasRecordCount" : true,
"historicalSnapshotDates" : [ ],
"id" : "00OR0000000K2UeMAK",
"name" : "Deals Closing This Quarter",
"reportBooleanFilter" : null,
"reportFilters" : [
{ "column" : "BucketField_36625466", "isRunPageEditable" : false, "operator" :
"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.
42
Get Report MetadataExamples: Reports REST API Resources
Example
This GET request, /services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/describe, to the Describe
resource returns metadata for a matrix report. This includes a bucket field, groupings, summaries, and a custom summary formula.
{
"reportTypeMetadata": {
"categories": [
{
"label": "Opportunity Information",
"columns": {
"CREATED": {
"filterValues": [],
"label": "Created By",
"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": {
43
Get Report MetadataExamples: Reports REST API Resources
"label": "Next Step",
"dataType": "string"
},
"BucketField_34840671": {
"label": "Industry",
"dataType": "string"
}
},
"aggregateColumnInfo": {
"RowCount": {
"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",
44
Get Report MetadataExamples: Reports REST API Resources
"currency": null,
"developerName": "StuckOpportunities",
"groupingsDown": [
{
"name": "ACCOUNT_NAME",
"sortOrder": "Asc",
"dateGranularity": "None"
},
{
"name": "CLOSE_DATE",
"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",
45
Get Report MetadataExamples: Reports REST API Resources
"BucketField_34840671"
]
}
}
SEE ALSO:
Describe
Get a List of Report Types
Return a list of analytics notifications using a GET request.
Use a GET request on the Report Type List resource to return a list of report types.
Example Usage
/services/data/v39.0/analytics/reportTypes
Example Response Body
[ {
"label" : "Accounts & Contacts",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountList",
"label" : "Accounts",
"type" : "AccountList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactList",
"label" : "Contacts & Accounts",
"type" : "ContactList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountPartner",
"label" : "Accounts with Partners",
"type" : "AccountPartner"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountTeam",
"label" : "Account with Account Teams",
"type" : "AccountTeam"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountContactRole",
"label" : "Accounts with Contact Roles",
"type" : "AccountContactRole"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountAsset",
"label" : "Accounts with Assets",
"type" : "AccountAsset"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactAsset",
"label" : "Contacts with Assets",
"type" : "ContactAsset"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountAuditHistory",
"label" : "Account History",
"type" : "AccountAuditHistory"
46
Get a List of Report TypesExamples: Reports REST API Resources
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactAuditHistory",
"label" : "Contact History",
"type" : "ContactAuditHistory"
} ]
}, {
"label" : "Opportunities",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/Opportunity",
"label" : "Opportunities",
"type" : "Opportunity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityProduct",
"label" : "Opportunities with Products",
"type" : "OpportunityProduct"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityContact",
"label" : "Opportunities with Contact Roles",
"type" : "OpportunityContact"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityPartner",
"label" : "Opportunities with Partners",
"type" : "OpportunityPartner"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityCompetitor",
"label" : "Opportunities with Competitors",
"type" : "OpportunityCompetitor"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityHistory",
"label" : "Opportunity History",
"type" : "OpportunityHistory"
}, {
"describeUrl" :
"/services/data/v39.0/analytics/reportTypes/OpportunityFieldAuditHistory",
"label" : "Opportunity Field History",
"type" : "OpportunityFieldAuditHistory"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityTrend",
"label" : "Opportunity Trends",
"type" : "OpportunityTrend"
}, {
"describeUrl" :
"/services/data/v39.0/analytics/reportTypes/OpportunityContactProduct",
"label" : "Opportunities with Contact Roles and Products",
"type" : "OpportunityContactProduct"
} ]
}, {
"label" : "Customer Support Reports",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseList",
"label" : "Cases",
"type" : "CaseList"
}, {
47
Get a List of Report TypesExamples: Reports REST API Resources
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseHistory",
"label" : "Case Lifecycle",
"type" : "CaseHistory"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseContactRole",
"label" : "Cases with Contact Roles",
"type" : "CaseContactRole"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseAsset",
"label" : "Cases with Assets",
"type" : "CaseAsset"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseSolution",
"label" : "Cases with Solutions",
"type" : "CaseSolution"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseAuditHistory",
"label" : "Case History",
"type" : "CaseAuditHistory"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionList",
"label" : "Solutions",
"type" : "SolutionList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionCategory",
"label" : "Solution Categories",
"type" : "SolutionCategory"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionAuditHistory",
"label" : "Solution History",
"type" : "SolutionAuditHistory"
} ]
}, {
"label" : "Leads",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LeadList",
"label" : "Leads",
"type" : "LeadList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityLead",
"label" : "Leads with converted lead information",
"type" : "OpportunityLead"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LeadAuditHistory",
"label" : "Lead History",
"type" : "LeadAuditHistory"
} ]
}, {
"label" : "Activities",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/Activity",
"label" : "Tasks and Events",
"type" : "Activity"
}, {
48
Get a List of Report TypesExamples: Reports REST API Resources
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/EventAttendee",
"label" : "Events with Invitees",
"type" : "EventAttendee"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/EmailStatus",
"label" : "HTML Email Status",
"type" : "EmailStatus"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AccountActivity",
"label" : "Activities with Accounts",
"type" : "AccountActivity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContactActivity",
"label" : "Activities with Contacts",
"type" : "ContactActivity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OpportunityActivity",
"label" : "Activities with Opportunities",
"type" : "OpportunityActivity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LeadActivity",
"label" : "Activities with Leads",
"type" : "LeadActivity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CaseActivity",
"label" : "Activities with Cases",
"type" : "CaseActivity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/SolutionActivity",
"label" : "Activities with Solutions",
"type" : "SolutionActivity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractActivity",
"label" : "Activities with Contracts",
"type" : "ContractActivity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductActivity",
"label" : "Activities with Products",
"type" : "ProductActivity"
} ]
}, {
"label" : "Contracts and Orders",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractList",
"label" : "Contracts",
"type" : "ContractList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractAuditHistory",
"label" : "Contract History",
"type" : "ContractAuditHistory"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractOrder",
"label" : "Contracts with Orders",
"type" : "ContractOrder"
49
Get a List of Report TypesExamples: Reports REST API Resources
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractOrderItem",
"label" : "Contracts with Orders and Products",
"type" : "ContractOrderItem"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ContractContactRole",
"label" : "Contracts with Contact Roles",
"type" : "ContractContactRole"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OrderList",
"label" : "Orders",
"type" : "OrderList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OrderItemList",
"label" : "Orders with Products",
"type" : "OrderItemList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/OrderAuditHistory",
"label" : "Order History",
"type" : "OrderAuditHistory"
} ]
}, {
"label" : "Price Books, Products and Assets",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductList",
"label" : "Products",
"type" : "ProductList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductOpportunity",
"label" : "Products with Opportunities",
"type" : "ProductOpportunity"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/PricebookProduct",
"label" : "Price Books with Products",
"type" : "PricebookProduct"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ProductAsset",
"label" : "Products with Assets",
"type" : "ProductAsset"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AssetWithProduct",
"label" : "Assets",
"type" : "AssetWithProduct"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/AssetCase",
"label" : "Assets with Cases",
"type" : "AssetCase"
} ]
}, {
"label" : "Administrative Reports",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/User",
"label" : "Users",
"type" : "User"
50
Get a List of Report TypesExamples: Reports REST API Resources
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/ReportList",
"label" : "Reports",
"type" : "ReportList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/DocumentList",
"label" : "Documents",
"type" : "DocumentList"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/LoginIpEmail",
"label" : "New Login Locations",
"type" : "LoginIpEmail"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/TwoFactorMethodsInfo",
"label" : "Identity Verification Methods",
"type" : "TwoFactorMethodsInfo"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CollabGroup",
"label" : "Collaboration Group Report",
"type" : "CollabGroup"
}, {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/CollabGroupFeedPosts",
"label" : "Collaboration Group Feed Posts Report",
"type" : "CollabGroupFeedPosts"
} ]
}, {
"label" : "File and Content Reports",
"reportTypes" : [ {
"describeUrl" : "/services/data/v39.0/analytics/reportTypes/File",
"label" : "File and Content Report",
"type" : "File"
} ]
} ]
List Asynchronous Runs of a Report
You can get as many as 2000 instances of a report for which you requested asynchronous runs by sending a GET request to the Instances
List resource. The instance list is sorted by the date when the run was requested. Report results are stored for a rolling 24-hour period.
During this time, based on your user access level, you can access results for each instance of the report that was run.
Example
A GET request, /services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/instances, to the Instances
List resource returns two instances of the report that was run asynchronously. Each URL handle stores report results for that instance.
[
{
"id": "0LGD000000000IyOAI",
"requestDate": "2013-08-12T19:06:47Z",
"status": "Success",
"url":
"/services/data/v29.0/analytics/reports/00OD0000001ZbP7MAK/instances/0LGD000000000IyOAI",
51
List Asynchronous Runs of a ReportExamples: Reports REST API Resources
"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, it’s helpful to check these properties in the metadata that tell you if a field can be filtered, the values and criteria
you can filter by, and filters that already exist in the report.
•filterable
•filterValues
•dataTypeFilterOperatorMap
•reportFilters
You can filter reports during synchronous or asynchronous report runs by making a POST request to the Execute Sync or Execute Async
resource.
Example
In a POST request, an accounts report is filtered synchronously by these passing filters with filter logic in the metadata to the Execute
Sync resource.
1. Account Name not equal to Data Mart
2. Account Owner not equal to Admin User
3. Annual Revenue greater than "100,000"
4. Industry not equal to Manufacturing,Recreation
52
Filter Reports on DemandExamples: Reports REST API Resources
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",
"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,
53
Filter Reports on DemandExamples: Reports REST API Resources
"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,
"label": "1"
}
]
},
"7_1!T": {
"aggregates": [
{
"value": 24000000,
"label": "$24,000,000"
},
{
"value": 1,
"label": "1"
}
]
},
...
"allData": true,
"reportMetadata": {
54
Filter Reports on DemandExamples: Reports REST API Resources
"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"
],
...
}
}
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
55
List Recently Viewed ReportsExamples: Reports REST API Resources
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",
"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
56
List Recently Viewed ReportsExamples: Reports REST API Resources
Decode the Fact Map
Depending on how you run a report, the fact map in the report results can contain values for only summary or both summary and
detailed data. The fact map values are expressed as keys, which you can programmatically use to visualize the report data. Fact map
keys provide an index into each section of a fact map, from which you can access summary and detailed data.
The pattern for the fact map keys varies by report format as shown in this table.
Fact map key patternReport
format
T!T: The grand total of a report. Both record data values and the grand total are represented by this key.Tabular
<First level row grouping_second level row grouping_third level row
grouping>!T: T refers to the row grand total.
Summary
<First level row grouping_second level row grouping>!<First level column
grouping_second level column grouping>.
Matrix
Each item in a row or column grouping is numbered starting with 0. Here are some examples of fact map keys:
DescriptionFact Map
Key
The first item in the first-level grouping.0!T
The second item in the first-level grouping.1!T
The first item in the first-level grouping and the first item in the second-level grouping.0_0!T
The first item in the first-level grouping and the second item in the second-level grouping.0_1!T
Let’s look at examples of how fact map keys represent data as it appears in a Salesforce tabular, summary, or matrix report.
Tabular Report Fact Map
Here’s an example of an opportunities report in tabular format. Since tabular reports don’t have groupings, all of the record level data
and summaries are expressed by the T!T key, which refers to the grand total.
57
Decode the Fact MapExamples: Reports REST API Resources
Summary Report Fact Map
This example shows how the values in a summary report are represented in the fact map.
DescriptionFact Map Key
Summary for the value of opportunities in the Prospecting stage.0!T
Summary of the probabilities for the Manufacturing opportunities in the Needs Analysis stage.1_0!T
58
Decode the Fact MapExamples: Reports REST API Resources
Matrix Report Fact Map
Here’s an example of some fact map keys for data in a matrix opportunities report with a couple of row and column groupings.
DescriptionFact Map Key
Total opportunity amount in the Prospecting stage in Q4 2010.0!0
Total opportunity amount in the Prospecting stage in the Manufacturing sector in October 2010.0_0!0_0
Total value of opportunities in the Value Proposition stage in the Technology sector in February 2011.2_1!1_1
Grand total summary for the report.T!T
SEE ALSO:
Execute Sync
Execute Async
Get Report Data without Saving Changes to or Creating a Report
Run a report without creating a report or changing an existing one by making a POST request to the query resource. Get report data
without filling up your org with unnecessary reports.
Example
Get report data using the query resource.
/services/data/v37.0/analytics/reports/query
Include report criteria as reportMetadata in the POST request body. This POST request gets data about Opportunities:
{
"reportMetadata" : {
"aggregates" : [ "RowCount" ],
"chart" : null,
59
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"crossFilters" : [ ],
"currency" : null,
"description" : null,
"detailColumns" : [ "OPPORTUNITY_NAME", "TYPE", "LEAD_SOURCE", "AMOUNT", "CLOSE_DATE",
"NEXT_STEP", "STAGE_NAME", "PROBABILITY", "FISCAL_QUARTER", "AGE", "CREATED_DATE",
"FULL_NAME", "ROLLUP_DESCRIPTION", "ACCOUNT_NAME" ],
"developerName" : "OpportunityReport",
"division" : null,
"folderId" : "00DD000000086ujMAA",
"groupingsAcross" : [ ],
"groupingsDown" : [ ],
"hasDetailRows" : true,
"hasRecordCount" : true,
"historicalSnapshotDates" : [ ],
"id" : "00OD0000001leVCMAY",
"name" : "Matrix",
"reportBooleanFilter" : null,
"reportFilters" : [ ],
"reportFormat" : "MATRIX",
"reportType" : {
"label" : "Opportunities",
"type" : "Opportunity"
},
"scope" : "organization",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CLOSE_DATE",
"durationValue" : "CUSTOM",
"endDate" : null,
"startDate" : null
},
"standardFilters" : [ {
"name" : "open",
"value" : "all"
}, {
"name" : "probability",
"value" : ">0"
} ]
}
}
The response to the POST request returns report data, but doesn’t create or save a report.
{
"attributes" : {
"describeUrl" : "/services/data/v37.0/analytics/reports/null/describe",
"instancesUrl" : "/services/data/v37.0/analytics/reports/null/instances",
"reportId" : null,
"reportName" : "Matrix",
"type" : "Report"
},
"allData" : true,
"factMap" : {
60
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"T!T" : {
"aggregates" : [ {
"label" : "9",
"value" : 9
} ],
"rows" : [ {
"dataCells" : [ {
"label" : "salesforce.com - 5000 Widgets",
"value" : "006D000000CzmqYIAR"
}, {
"label" : "New Business",
"value" : "New Business"
}, {
"label" : "Advertisement",
"value" : "Advertisement"
}, {
"label" : "$500,000.00",
"value" : {
"amount" : 500000,
"currency" : null
}
}, {
"label" : "9/19/2013",
"value" : "2013-09-19"
}, {
"label" : "Closed!",
"value" : "Closed!"
}, {
"label" : "Closed Won",
"value" : "Closed Won"
}, {
"label" : "100%",
"value" : 100
}, {
"label" : "Q2-2007",
"value" : "Q2-2007"
}, {
"label" : "0",
"value" : 0
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "Global Media",
"value" : "001D000000KtTTqIAN"
} ]
}, {
"dataCells" : [ {
61
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"label" : "salesforce.com - 500 Widgets",
"value" : "006D000000CzmqZIAR"
}, {
"label" : "Existing Business",
"value" : "Existing Business"
}, {
"label" : "Advertisement",
"value" : "Advertisement"
}, {
"label" : "$50,000.00",
"value" : {
"amount" : 50000,
"currency" : null
}
}, {
"label" : "9/19/2013",
"value" : "2013-09-19"
}, {
"label" : "Closed!",
"value" : "Closed!"
}, {
"label" : "Closed Won",
"value" : "Closed Won"
}, {
"label" : "100%",
"value" : 100
}, {
"label" : "Q2-2007",
"value" : "Q2-2007"
}, {
"label" : "0",
"value" : 0
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "Global Media",
"value" : "001D000000KtTTqIAN"
} ]
}, {
"dataCells" : [ {
"label" : "Acme - 1,200 Widgets",
"value" : "006D000000CzmqbIAB"
}, {
"label" : "Existing Business",
"value" : "Existing Business"
}, {
"label" : "Trade Show",
62
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"value" : "Trade Show"
}, {
"label" : "$140,000.00",
"value" : {
"amount" : 140000,
"currency" : null
}
}, {
"label" : "10/22/2013",
"value" : "2013-10-22"
}, {
"label" : "Need estimate",
"value" : "Need estimate"
}, {
"label" : "Value Proposition",
"value" : "Value Proposition"
}, {
"label" : "50%",
"value" : 50
}, {
"label" : "Q2-2007",
"value" : "Q2-2007"
}, {
"label" : "134",
"value" : 134
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "Acme",
"value" : "001D000000KtTTrIAN"
} ]
}, {
"dataCells" : [ {
"label" : "salesforce.com - 1,000 Widgets",
"value" : "006D000000CzmqeIAB"
}, {
"label" : "New Business",
"value" : "New Business"
}, {
"label" : "Advertisement",
"value" : "Advertisement"
}, {
"label" : "$100,000.00",
"value" : {
"amount" : 100000,
"currency" : null
}
63
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
}, {
"label" : "10/22/2013",
"value" : "2013-10-22"
}, {
"label" : "Close the deal!",
"value" : "Close the deal!"
}, {
"label" : "Negotiation/Review",
"value" : "Negotiation/Review"
}, {
"label" : "90%",
"value" : 90
}, {
"label" : "Q2-2007",
"value" : "Q2-2007"
}, {
"label" : "134",
"value" : 134
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "salesforce.com",
"value" : "001D000000KtTTsIAN"
} ]
}, {
"dataCells" : [ {
"label" : "Global Media - 400 Widgets",
"value" : "006D000000CzmqaIAB"
}, {
"label" : "New Business",
"value" : "New Business"
}, {
"label" : "Partner",
"value" : "Partner"
}, {
"label" : "$40,000.00",
"value" : {
"amount" : 40000,
"currency" : null
}
}, {
"label" : "11/20/2013",
"value" : "2013-11-20"
}, {
"label" : "-",
"value" : null
}, {
64
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"label" : "Id. Decision Makers",
"value" : "Id. Decision Makers"
}, {
"label" : "60%",
"value" : 60
}, {
"label" : "Q3-2007",
"value" : "Q3-2007"
}, {
"label" : "134",
"value" : 134
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "Global Media",
"value" : "001D000000KtTTqIAN"
} ]
}, {
"dataCells" : [ {
"label" : "Acme - 600 Widgets",
"value" : "006D000000CzmqcIAB"
}, {
"label" : "New Business",
"value" : "New Business"
}, {
"label" : "Trade Show",
"value" : "Trade Show"
}, {
"label" : "$70,000.00",
"value" : {
"amount" : 70000,
"currency" : null
}
}, {
"label" : "12/18/2013",
"value" : "2013-12-18"
}, {
"label" : "Need estimate",
"value" : "Need estimate"
}, {
"label" : "Needs Analysis",
"value" : "Needs Analysis"
}, {
"label" : "20%",
"value" : 20
}, {
"label" : "Q3-2007",
65
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"value" : "Q3-2007"
}, {
"label" : "134",
"value" : 134
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "Acme",
"value" : "001D000000KtTTrIAN"
} ]
}, {
"dataCells" : [ {
"label" : "salesforce.com - 2,000 Widgets",
"value" : "006D000000CzmqfIAB"
}, {
"label" : "Existing Business",
"value" : "Existing Business"
}, {
"label" : "Partner",
"value" : "Partner"
}, {
"label" : "$20,000.00",
"value" : {
"amount" : 20000,
"currency" : null
}
}, {
"label" : "12/20/2013",
"value" : "2013-12-20"
}, {
"label" : "Meet at Widget Conference",
"value" : "Meet at Widget Conference"
}, {
"label" : "Value Proposition",
"value" : "Value Proposition"
}, {
"label" : "50%",
"value" : 50
}, {
"label" : "Q3-2007",
"value" : "Q3-2007"
}, {
"label" : "134",
"value" : 134
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
66
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "salesforce.com",
"value" : "001D000000KtTTsIAN"
} ]
}, {
"dataCells" : [ {
"label" : "Acme - 200 Widgets",
"value" : "006D000000CzmqdIAB"
}, {
"label" : "Existing Business",
"value" : "Existing Business"
}, {
"label" : "Word of mouth",
"value" : "Word of mouth"
}, {
"label" : "$20,000.00",
"value" : {
"amount" : 20000,
"currency" : null
}
}, {
"label" : "2/20/2014",
"value" : "2014-02-20"
}, {
"label" : "Need estimate",
"value" : "Need estimate"
}, {
"label" : "Prospecting",
"value" : "Prospecting"
}, {
"label" : "10%",
"value" : 10
}, {
"label" : "Q4-2007",
"value" : "Q4-2007"
}, {
"label" : "134",
"value" : 134
}, {
"label" : "1/4/2016",
"value" : "2016-01-04"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
67
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"label" : "Acme",
"value" : "001D000000KtTTrIAN"
} ]
}, {
"dataCells" : [ {
"label" : "Fred",
"value" : "006D000000Czq0uIAB"
}, {
"label" : "-",
"value" : null
}, {
"label" : "-",
"value" : null
}, {
"label" : "-",
"value" : null
}, {
"label" : "2/26/2016",
"value" : "2016-02-26"
}, {
"label" : "-",
"value" : null
}, {
"label" : "Id. Decision Makers",
"value" : "Id. Decision Makers"
}, {
"label" : "60%",
"value" : 60
}, {
"label" : "Q1-2016",
"value" : "Q1-2016"
}, {
"label" : "85",
"value" : 85
}, {
"label" : "2/22/2016",
"value" : "2016-02-22"
}, {
"label" : "Fred Williamson",
"value" : "005D0000001bV42IAE"
}, {
"label" : "-",
"value" : null
}, {
"label" : "Fred",
"value" : "001D000000KtqzeIAB"
} ]
} ]
}
},
"groupingsAcross" : {
"groupings" : [ ]
},
"groupingsDown" : {
68
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"groupings" : [ ]
},
"hasDetailRows" : true,
"reportExtendedMetadata" : {
"aggregateColumnInfo" : {
"RowCount" : {
"dataType" : "int",
"label" : "Record Count"
}
},
"detailColumnInfo" : {
"OPPORTUNITY_NAME" : {
"dataType" : "string",
"label" : "Opportunity Name"
},
"TYPE" : {
"dataType" : "picklist",
"label" : "Type"
},
"LEAD_SOURCE" : {
"dataType" : "picklist",
"label" : "Lead Source"
},
"AMOUNT" : {
"dataType" : "currency",
"label" : "Amount"
},
"CLOSE_DATE" : {
"dataType" : "date",
"label" : "Close Date"
},
"NEXT_STEP" : {
"dataType" : "string",
"label" : "Next Step"
},
"STAGE_NAME" : {
"dataType" : "picklist",
"label" : "Stage"
},
"PROBABILITY" : {
"dataType" : "percent",
"label" : "Probability (%)"
},
"FISCAL_QUARTER" : {
"dataType" : "string",
"label" : "Fiscal Period"
},
"AGE" : {
"dataType" : "int",
"label" : "Age"
},
"CREATED_DATE" : {
"dataType" : "datetime",
"label" : "Created Date"
69
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
},
"FULL_NAME" : {
"dataType" : "string",
"label" : "Opportunity Owner"
},
"ROLLUP_DESCRIPTION" : {
"dataType" : "string",
"label" : "Owner Role"
},
"ACCOUNT_NAME" : {
"dataType" : "string",
"label" : "Account Name"
}
},
"groupingColumnInfo" : { }
},
"reportMetadata" : {
"aggregates" : [ "RowCount" ],
"chart" : null,
"crossFilters" : [ ],
"currency" : null,
"description" : null,
"detailColumns" : [ "OPPORTUNITY_NAME", "TYPE", "LEAD_SOURCE", "AMOUNT", "CLOSE_DATE",
"NEXT_STEP", "STAGE_NAME", "PROBABILITY", "FISCAL_QUARTER", "AGE", "CREATED_DATE",
"FULL_NAME", "ROLLUP_DESCRIPTION", "ACCOUNT_NAME" ],
"developerName" : null,
"division" : null,
"folderId" : "00DD000000086ujMAA",
"groupingsAcross" : [ ],
"groupingsDown" : [ ],
"hasDetailRows" : true,
"hasRecordCount" : true,
"historicalSnapshotDates" : [ ],
"id" : null,
"name" : "Matrix",
"reportBooleanFilter" : null,
"reportFilters" : [ ],
"reportFormat" : "TABULAR",
"reportType" : {
"label" : "Opportunities",
"type" : "Opportunity"
},
"scope" : "organization",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CLOSE_DATE",
"durationValue" : "CUSTOM",
"endDate" : null,
"startDate" : null
},
"standardFilters" : [ {
"name" : "open",
70
Get Report Data without Saving Changes to or Creating a
Report
Examples: Reports REST API Resources
"value" : "all"
}, {
"name" : "probability",
"value" : ">0"
} ]
}
}
Save Changes to Reports
Save changes to a report by sending a PATCH request to the Report resource.
Note: Saving a report deletes any running async report jobs because they will be obsolete.
Example
For report 00OD0000001cxIE, you want to change the report name to “myUpdatedReport” and change the folder that contains the
report. You save the changes to the report.
This PATCH request /services/data/v34.0/analytics/reports/00OD0000001cxIE to the Report resource updates
and saves the report.
{
"reportMetadata" : {
"name":"myUpdatedReport",
"folderId":"00DD00000007enH"}
}
The response to the PATCH request returns the following details about the updated, saved report.
{
"reportExtendedMetadata" : {
...
},
"reportMetadata" : {
"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,
71
Save Changes to ReportsExamples: Reports REST API Resources
"historicalSnapshotDates" : [ ],
"id" : "00OD0000001cxIEMAY",
"name" : "myUpdatedReport",
"reportBooleanFilter" : null,
"reportFilters" : [ ],
"reportFormat" : "TABULAR",
"reportType" : {
"label" : "Accounts",
"type" : "AccountList" },
"scope" : "user",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CREATED_DATE",
"durationValue" : "CUSTOM",
"endDate" : null,
"startDate" : null },
"standardFilters" : null },
"reportTypeMetadata" : {
...
}
}
Clone Reports
Creates a copy of a custom, standard, or public report by sending a POST request to the Report List resource.
Example
You want to clone report 00OD0000001cxIE and name the cloned report as "myNewReport."
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",
72
Clone ReportsExamples: Reports REST API Resources
"TYPE",
"DUE_DATE",
"LAST_UPDATE",
"ADDRESS1_STATE" ],
"developerName" : "myreport2",
"division" : null,
"folderId" : "005D0000001UlszIAC",
"groupingsAcross" : [ ],
"groupingsDown" : [ ],
"hasDetailRows" : true,
"hasRecordCount" : true,
"historicalSnapshotDates" : [ ],
"id" : "00OD0000001jabSMAQ",
"name" : "myNewReport",
"reportBooleanFilter" : null,
"reportFilters" : [ ],
"reportFormat" : "TABULAR",
"reportType" : {
"label" : "Accounts",
"type" : "AccountList" },
"scope" : "user",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CREATED_DATE",
"durationValue" : "CUSTOM",
"endDate" : null,
"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.
73
Delete ReportsExamples: Reports REST API Resources
CHAPTER 3 Examples: Dashboards REST API Resources
The Dashboards API is designed to let you access and refresh dashboards easily. Use the API to:
In this chapter ...
•Get List of Recently Used Dashboards
Get a list of dashboards with URLs to access status and results.
•Get List of Recently
Used Dashboards
•Get Dashboard
Results •Get Dashboard Results
Get dashboard metadata, data, and status.
•Filter Dashboard
Results •Filter Dashboard Results
Filter dashboard results, status, or refresh requests.
•Get Dashboard
Status
•Get Dashboard Status
Get dashboard refresh status.
•Refresh a Dashboard
•Save a Dashboard
•Return Details About
Dashboard
Components
•Refresh a Dashboard
Trigger a dashboard refresh.
•Get Dashboard
Metadata •Save a Dashboard
Save changes to a dashboard.
•Clone a Dashboard
•Clone a Dashboard
Make a copy of an existing dashboard.
•Delete a Dashboard
•Delete a Dashboard
Clean up unused and obsolete dashboards.
74
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" : [ {
75
Get List of Recently Used DashboardsExamples: Dashboards REST API Resources
"componentId" : "01aD0000000a36LIAQ",
"reportResult" : {
"attributes" : null,
"allData" : true,
"factMap" : {
"T!T" : {
"aggregates" : [ {
"label" : "USD 67,043,365.50",
"value" : 67043365.50166918337345123291015625
} ]
},
"0!T" : {
"aggregates" : [ {
"label" : "USD 10,083.33",
"value" : 10083.333333333333939663134515285491943359375
} ]
},
"1!T" : {
"aggregates" : [ {
"label" : "USD 25,016,768.67",
"value" : 25016768.670066006481647491455078125
} ]
},
"2!T" : {
"aggregates" : [ {
"label" : "USD 42,016,513.50",
"value" : 42016513.49826984107494354248046875
} ]
}
},
"groupingsAcross" : null,
"groupingsDown" : {
"groupings" : [ {
"groupings" : [ ],
"key" : "0",
"label" : "-",
"value" : null
}, {
"groupings" : [ ],
"key" : "1",
"label" : "Existing Business",
"value" : "Existing Business"
}, {
"groupings" : [ ],
"key" : "2",
"label" : "New Business",
"value" : "New Business"
} ]
},
"hasDetailRows" : false,
"reportExtendedMetadata" : {
"aggregateColumnInfo" : {
"s!AMOUNT" : {
"acrossGroupingContext" : null,
76
Get Dashboard ResultsExamples: Dashboards REST API Resources
"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" : {
77
Get Dashboard ResultsExamples: Dashboards REST API Resources
"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,
78
Get Dashboard ResultsExamples: Dashboards REST API Resources
"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
} ], [ {
79
Filter Dashboard ResultsExamples: Dashboards REST API Resources
"id" : "0ICxx0000000002GAA",
"alias" : "Canada",
"operation" : "equals",
"value" : "CA",
"startValue" : null,
"endValue" : null
} ],
...
}
To retrieve dashboard results with a filter of "Country equals Canada" you could make the following GET request:
/services/data/v31.0/analytics/dashboards/01Zxx0000000000000?filter1=0ICxx0000000002GAA
SEE ALSO:
Dashboard Results
Dashboard Status
Get Dashboard Status
You can get the dashboard status by sending a GET request to the Dashboard Status resource.
Use the Dashboard Status resource to retrieve a status for each component of the dashboard. The components are listed in the order in
which they were refreshed. The request returns IDLE if a component is not currently being refreshed, and RUNNING if a component
is currently being refreshed.
Example Usage
To retrieve the status for a dashboard with an ID of 01ZD00000007QevMAE, you could make the following request:
/services/data/v31.0/analytics/dashboards/01ZD00000007QevMAE/status
Example Response Body
The response contains the status for each component, along with the refresh date and time:
{
"componentStatus" : [ {
"componentId" : "01aD0000000J7M7",
"refreshDate" : "2014-03-10T17:26:07.000+0000",
"refreshStatus" : "IDLE"
}, {
"componentId" : "01aD0000000J7M9",
"refreshDate" : "2014-03-10T17:26:08.000+0000",
"refreshStatus" : "IDLE"
}, {
"componentId" : "01aD0000000J7MB",
"refreshDate" : "2014-03-10T17:26:09.000+0000",
"refreshStatus" : "IDLE"
80
Get Dashboard StatusExamples: Dashboards REST API Resources
} ]
}
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",
}
}
81
Refresh a DashboardExamples: Dashboards REST API Resources
Example Response Body
{
"componentData" : [ {
"componentId" : "01aD0000000a36LIAQ",
"reportResult" : {
"attributes" : null,
"allData" : true,
"factMap" : {
"T!T" : {
"aggregates" : [ {
"label" : "USD 67,043,365.50",
"value" : 67043365.50166918337345123291015625
} ]
},
"0!T" : {
"aggregates" : [ {
"label" : "USD 10,083.33",
"value" : 10083.333333333333939663134515285491943359375
} ]
},
"1!T" : {
"aggregates" : [ {
"label" : "USD 25,016,768.67",
"value" : 25016768.670066006481647491455078125
} ]
},
"2!T" : {
"aggregates" : [ {
"label" : "USD 42,016,513.50",
"value" : 42016513.49826984107494354248046875
} ]
}
},
"groupingsAcross" : null,
"groupingsDown" : {
"groupings" : [ {
"groupings" : [ ],
"key" : "0",
"label" : "-",
"value" : null
}, {
"groupings" : [ ],
"key" : "1",
"label" : "Existing Business",
"value" : "Existing Business"
}, {
"groupings" : [ ],
"key" : "2",
"label" : "New Business",
"value" : "New Business"
} ]
},
"hasDetailRows" : false,
82
Save a DashboardExamples: Dashboards REST API Resources
"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" },
83
Save a DashboardExamples: Dashboards REST API Resources
{ "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,
84
Save a DashboardExamples: Dashboards REST API Resources
"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"
}
}
}
Return Details About Dashboard Components
Get details about one or more dashboard components using a POST request.
Use a POST request on the Dashboard Results resource to get details about one or more dashboard components. Specify which dashboard
components you want details about using componentIds in the request body. Available in API versions 36.0 and later.
Example Usage
/services/data/v36.0/analytics/dashboards/01ZR00000008h2EMAQ
Example Request Body
{
"componentIds": ["01aR00000005aT4IAI", "01aR00000005aT5IAI"]
}
Example Response Body
{
"attributes" : {
"dashboardId" : "01ZR00000008h2EMAQ",
"dashboardName" : "Liz's Sales Manager Dashboard",
"describeUrl" :
"/services/data/v37.0/analytics/dashboards/01ZR00000008h2EMAQ/describe",
"statusUrl" : "/services/data/v37.0/analytics/dashboards/01ZR00000008h2EMAQ/status",
"type" : "Dashboard"
},
"componentData" : [ {
"componentId" : "01aR00000005aT4IAI",
"reportResult" : {
85
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"attributes" : null,
"allData" : true,
"factMap" : {
"0!T" : {
"aggregates" : [ {
"label" : "$10,000.00",
"value" : 10000
} ]
},
"1!T" : {
"aggregates" : [ {
"label" : "$110,000.00",
"value" : 110000
} ]
},
"0_0!T" : {
"aggregates" : [ {
"label" : "$10,000.00",
"value" : 10000
} ]
},
"2_2!T" : {
"aggregates" : [ {
"label" : "$143.00",
"value" : 143
} ]
},
"2!T" : {
"aggregates" : [ {
"label" : "$400,398.00",
"value" : 400398
} ]
},
"0_1!T" : {
"aggregates" : [ {
"label" : "$0.00",
"value" : 0
} ]
},
"2_3!T" : {
"aggregates" : [ {
"label" : "$100,017.00",
"value" : 100017
} ]
},
"T!T" : {
"aggregates" : [ {
"label" : "$520,398.00",
"value" : 520398
} ]
},
"2_0!T" : {
"aggregates" : [ {
"label" : "$138.00",
86
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"value" : 138
} ]
},
"1_0!T" : {
"aggregates" : [ {
"label" : "$110,000.00",
"value" : 110000
} ]
},
"2_1!T" : {
"aggregates" : [ {
"label" : "$300,100.00",
"value" : 300100
} ]
}
},
"groupingsAcross" : null,
"groupingsDown" : {
"groupings" : [ {
"groupings" : [ {
"groupings" : [ ],
"key" : "0_0",
"label" : "-",
"value" : null
}, {
"groupings" : [ ],
"key" : "0_1",
"label" : "-",
"value" : null
} ],
"key" : "0",
"label" : "January 2016",
"value" : "January 2016"
}, {
"groupings" : [ {
"groupings" : [ ],
"key" : "1_0",
"label" : "-",
"value" : null
} ],
"key" : "1",
"label" : "February 2016",
"value" : "February 2016"
}, {
"groupings" : [ {
"groupings" : [ ],
"key" : "2_0",
"label" : "-",
"value" : null
}, {
"groupings" : [ ],
"key" : "2_1",
"label" : "-",
"value" : null
87
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
}, {
"groupings" : [ ],
"key" : "2_2",
"label" : "-",
"value" : null
}, {
"groupings" : [ ],
"key" : "2_3",
"label" : "-",
"value" : null
} ],
"key" : "2",
"label" : "March 2016",
"value" : "March 2016"
} ]
},
"hasDetailRows" : false,
"reportExtendedMetadata" : {
"aggregateColumnInfo" : {
"s!AMOUNT" : {
"dataType" : "currency",
"label" : "Sum of Amount"
}
},
"detailColumnInfo" : { },
"groupingColumnInfo" : {
"ACCOUNT_NAME" : {
"dataType" : "string",
"groupingLevel" : 0,
"label" : "Account Name"
},
"CLOSE_DATE" : {
"dataType" : "date",
"groupingLevel" : 0,
"label" : "Close Date"
}
}
},
"reportMetadata" : {
"aggregates" : [ "s!AMOUNT" ],
"buckets" : [ {
"bucketType" : "picklist",
"devloperName" : "BucketField_47575792",
"label" : "Industry",
"nullTreatedAsZero" : false,
"otherBucketLabel" : null,
"sourceColumnName" : "INDUSTRY",
"values" : [ {
"label" : "Technology",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Agriculture", "Apparel", "Banking",
"Biotechnology", "Chemicals", "Communications", "Construction", "Consulting", "Education",
"Electronics" ]
}, {
88
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"label" : "Energy",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Energy", "Engineering", "Entertainment",
"Environmental", "Finance", "Food & Beverage", "Government", "Healthcare", "Hospitality",
"Insurance", "Machinery", "Manufacturing" ]
}, {
"label" : "Healthcare",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Media", "Not For Profit", "Other", "Recreation",
"Retail", "Shipping", "Technology", "Telecommunications", "Transportation", "Utilities"
]
} ]
}, {
"bucketType" : "picklist",
"devloperName" : "BucketField_36625466",
"label" : "Stage",
"nullTreatedAsZero" : false,
"otherBucketLabel" : null,
"sourceColumnName" : "STAGE_NAME",
"values" : [ {
"label" : "Early",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Prospecting", "Qualification", "Needs Analysis"
]
}, {
"label" : "Late",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Value Proposition", "Id. Decision Makers",
"Perception Analysis", "Proposal/Price Quote", "Negotiation/Review" ]
}, {
"label" : "Won",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Closed Won" ]
}, {
"label" : "Lost",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Closed Lost" ]
} ]
} ],
"chart" : null,
"crossFilters" : [ ],
"currency" : null,
"description" : null,
"detailColumns" : [ ],
"developerName" : "Deals_Closing_This_Quarter",
"division" : null,
"folderId" : "00lR0000000M8IiIAK",
"groupingsAcross" : [ ],
"groupingsDown" : [ {
"dateGranularity" : "None",
"name" : "ACCOUNT_NAME",
"sortAggregate" : null,
"sortOrder" : "Asc"
}, {
89
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"dateGranularity" : "Month",
"name" : "CLOSE_DATE",
"sortAggregate" : null,
"sortOrder" : "Asc"
} ],
"hasDetailRows" : false,
"hasRecordCount" : true,
"historicalSnapshotDates" : [ ],
"id" : "00OR0000000K2UeMAK",
"name" : "Deals Closing This Quarter",
"reportBooleanFilter" : null,
"reportFilters" : [ {
"column" : "BucketField_36625466",
"isRunPageEditable" : true,
"operator" : "equals",
"value" : "Early,Late"
}, {
"column" : "TYPE",
"isRunPageEditable" : true,
"operator" : "equals",
"value" : "Existing Business,New Business"
} ],
"reportFormat" : "SUMMARY",
"reportType" : {
"label" : "Opportunities",
"type" : "Opportunity"
},
"scope" : "organization",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CLOSE_DATE",
"durationValue" : "THIS_FISCAL_QUARTER",
"endDate" : "2016-06-30",
"startDate" : "2016-04-01"
},
"standardFilters" : [ {
"name" : "open",
"value" : "all"
}, {
"name" : "probability",
"value" : ">0"
} ]
}
},
"status" : {
"dataStatus" : "DATA",
"errorCode" : null,
"errorMessage" : null,
"errorSeverity" : null,
"refreshDate" : "2016-03-22T18:24:39.000+0000",
"refreshStatus" : "IDLE"
}
90
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
}, {
"componentId" : "01aR00000005aT5IAI",
"reportResult" : {
"attributes" : null,
"allData" : true,
"factMap" : {
"0!T" : {
"aggregates" : [ {
"label" : "$634,493.00",
"value" : 634493
} ]
},
"1!T" : {
"aggregates" : [ {
"label" : "$590,036.00",
"value" : 590036
} ]
},
"0_0!T" : {
"aggregates" : [ {
"label" : "$14.00",
"value" : 14
} ]
},
"2!T" : {
"aggregates" : [ {
"label" : "$1,330,035.00",
"value" : 1330035
} ]
},
"0_1!T" : {
"aggregates" : [ {
"label" : "$36,021.00",
"value" : 36021
} ]
},
"0_2!T" : {
"aggregates" : [ {
"label" : "$5,000.00",
"value" : 5000
} ]
},
"1_3!T" : {
"aggregates" : [ {
"label" : "$500,000.00",
"value" : 500000
} ]
},
"T!T" : {
"aggregates" : [ {
"label" : "$2,554,564.00",
"value" : 2554564
} ]
},
91
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"0_3!T" : {
"aggregates" : [ {
"label" : "$440,000.00",
"value" : 440000
} ]
},
"1_4!T" : {
"aggregates" : [ {
"label" : "$13.00",
"value" : 13
} ]
},
"0_4!T" : {
"aggregates" : [ {
"label" : "$20,000.00",
"value" : 20000
} ]
},
"1_1!T" : {
"aggregates" : [ {
"label" : "$11.00",
"value" : 11
} ]
},
"0_5!T" : {
"aggregates" : [ {
"label" : "$90,000.00",
"value" : 90000
} ]
},
"1_2!T" : {
"aggregates" : [ {
"label" : "$40,000.00",
"value" : 40000
} ]
},
"0_6!T" : {
"aggregates" : [ {
"label" : "$43,320.00",
"value" : 43320
} ]
},
"0_7!T" : {
"aggregates" : [ {
"label" : "$138.00",
"value" : 138
} ]
},
"1_0!T" : {
"aggregates" : [ {
"label" : "$50,012.00",
"value" : 50012
} ]
},
92
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"2_2!T" : {
"aggregates" : [ {
"label" : "$100,017.00",
"value" : 100017
} ]
},
"2_3!T" : {
"aggregates" : [ {
"label" : "$20,018.00",
"value" : 20018
} ]
},
"2_4!T" : {
"aggregates" : [ {
"label" : "$0.00",
"value" : 0
} ]
},
"2_0!T" : {
"aggregates" : [ {
"label" : "$100,000.00",
"value" : 100000
} ]
},
"2_1!T" : {
"aggregates" : [ {
"label" : "$1,110,000.00",
"value" : 1110000
} ]
}
},
"groupingsAcross" : null,
"groupingsDown" : {
"groupings" : [ {
"groupings" : [ {
"groupings" : [ ],
"key" : "0_0",
"label" : "March 2013",
"value" : "2013-03-01"
}, {
"groupings" : [ ],
"key" : "0_1",
"label" : "July 2015",
"value" : "2015-07-01"
}, {
"groupings" : [ ],
"key" : "0_2",
"label" : "August 2015",
"value" : "2015-08-01"
}, {
"groupings" : [ ],
"key" : "0_3",
"label" : "September 2015",
"value" : "2015-09-01"
93
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
}, {
"groupings" : [ ],
"key" : "0_4",
"label" : "October 2015",
"value" : "2015-10-01"
}, {
"groupings" : [ ],
"key" : "0_5",
"label" : "November 2015",
"value" : "2015-11-01"
}, {
"groupings" : [ ],
"key" : "0_6",
"label" : "December 2015",
"value" : "2015-12-01"
}, {
"groupings" : [ ],
"key" : "0_7",
"label" : "March 2016",
"value" : "2016-03-01"
} ],
"key" : "0",
"label" : "Manufacturing",
"value" : "Manufacturing"
}, {
"groupings" : [ {
"groupings" : [ ],
"key" : "1_0",
"label" : "February 2013",
"value" : "2013-02-01"
}, {
"groupings" : [ ],
"key" : "1_1",
"label" : "February 2015",
"value" : "2015-02-01"
}, {
"groupings" : [ ],
"key" : "1_2",
"label" : "September 2015",
"value" : "2015-09-01"
}, {
"groupings" : [ ],
"key" : "1_3",
"label" : "February 2016",
"value" : "2016-02-01"
}, {
"groupings" : [ ],
"key" : "1_4",
"label" : "April 2016",
"value" : "2016-04-01"
} ],
"key" : "1",
"label" : "Media",
"value" : "Media"
94
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
}, {
"groupings" : [ {
"groupings" : [ ],
"key" : "2_0",
"label" : "November 2015",
"value" : "2015-11-01"
}, {
"groupings" : [ ],
"key" : "2_1",
"label" : "December 2015",
"value" : "2015-12-01"
}, {
"groupings" : [ ],
"key" : "2_2",
"label" : "March 2016",
"value" : "2016-03-01"
}, {
"groupings" : [ ],
"key" : "2_3",
"label" : "May 2016",
"value" : "2016-05-01"
}, {
"groupings" : [ ],
"key" : "2_4",
"label" : "June 2016",
"value" : "2016-06-01"
} ],
"key" : "2",
"label" : "Technology",
"value" : "Technology"
} ]
},
"hasDetailRows" : false,
"reportExtendedMetadata" : {
"aggregateColumnInfo" : {
"s!AMOUNT" : {
"dataType" : "currency",
"label" : "Sum of Amount"
}
},
"detailColumnInfo" : { },
"groupingColumnInfo" : {
"INDUSTRY" : {
"dataType" : "picklist",
"groupingLevel" : 0,
"label" : "Industry"
},
"CLOSE_DATE" : {
"dataType" : "date",
"groupingLevel" : 0,
"label" : "Close Date"
}
}
},
95
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"reportMetadata" : {
"aggregates" : [ "s!AMOUNT" ],
"buckets" : [ {
"bucketType" : "picklist",
"devloperName" : "BucketField_47575792",
"label" : "Industry",
"nullTreatedAsZero" : false,
"otherBucketLabel" : null,
"sourceColumnName" : "INDUSTRY",
"values" : [ {
"label" : "Technology",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Agriculture", "Apparel", "Banking",
"Biotechnology", "Chemicals", "Communications", "Construction", "Consulting", "Education",
"Electronics" ]
}, {
"label" : "Energy",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Energy", "Engineering", "Entertainment",
"Environmental", "Finance", "Food & Beverage", "Government", "Healthcare", "Hospitality",
"Insurance", "Machinery", "Manufacturing" ]
}, {
"label" : "Healthcare",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Media", "Not For Profit", "Other", "Recreation",
"Retail", "Shipping", "Technology", "Telecommunications", "Transportation", "Utilities"
]
} ]
}, {
"bucketType" : "picklist",
"devloperName" : "BucketField_36625466",
"label" : "Stage",
"nullTreatedAsZero" : false,
"otherBucketLabel" : null,
"sourceColumnName" : "STAGE_NAME",
"values" : [ {
"label" : "Early",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Prospecting", "Qualification", "Needs Analysis"
]
}, {
"label" : "Late",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Value Proposition", "Id. Decision Makers",
"Perception Analysis", "Proposal/Price Quote", "Negotiation/Review" ]
}, {
"label" : "Won",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Closed Won" ]
}, {
"label" : "Lost",
"rangeUpperBound" : null,
"sourceDimensionValues" : [ "Closed Lost" ]
} ]
96
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
} ],
"chart" : null,
"crossFilters" : [ ],
"currency" : null,
"description" : null,
"detailColumns" : [ ],
"developerName" : "Pipeline_By_Industry1",
"division" : null,
"folderId" : "005R0000000Hv5rIAC",
"groupingsAcross" : [ ],
"groupingsDown" : [ {
"dateGranularity" : "None",
"name" : "INDUSTRY",
"sortAggregate" : null,
"sortOrder" : "Asc"
}, {
"dateGranularity" : "Month",
"name" : "CLOSE_DATE",
"sortAggregate" : null,
"sortOrder" : "Asc"
} ],
"hasDetailRows" : true,
"hasRecordCount" : false,
"historicalSnapshotDates" : [ ],
"id" : "00OR0000000OgsOMAS",
"name" : "Copy of Pipeline By Industry",
"reportBooleanFilter" : null,
"reportFilters" : [ {
"column" : "ACCOUNT_TYPE",
"isRunPageEditable" : false,
"operator" : "lessOrEqual",
"value" : "Integrator,Partner,Prospect"
}, {
"column" : "INDUSTRY",
"isRunPageEditable" : true,
"operator" : "notEqual",
"value" : ""
} ],
"reportFormat" : "SUMMARY",
"reportType" : {
"label" : "Opportunities",
"type" : "Opportunity"
},
"scope" : "organization",
"showGrandTotal" : true,
"showSubtotals" : true,
"sortBy" : [ ],
"standardDateFilter" : {
"column" : "CLOSE_DATE",
"durationValue" : "CUSTOM",
"endDate" : null,
"startDate" : null
},
"standardFilters" : [ {
97
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"name" : "open",
"value" : "all"
}, {
"name" : "probability",
"value" : ">0"
} ]
}
},
"status" : {
"dataStatus" : "DATA",
"errorCode" : null,
"errorMessage" : null,
"errorSeverity" : null,
"refreshDate" : "2016-03-22T18:24:39.000+0000",
"refreshStatus" : "IDLE"
}
} ],
"dashboardMetadata" : {
"canChangeRunningUser" : false,
"components" : [ {
"componentData" : 0,
"footer" : null,
"header" : "Pipeline This Quarter",
"id" : "01aR00000005aT4IAI",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
} ],
"autoSelectColumns" : false,
"filterColumns" : [ ],
"groupings" : null,
"maxRows" : null,
"sort" : null,
"useReportChart" : false,
"visualizationProperties" : {
"breakPoints" : [ {
"aggregateName" : "s!AMOUNT",
"breaks" : [ {
"color" : "c23934",
"lowerBound" : 0,
"upperBound" : 200000
}, {
"color" : "ffb75d",
"lowerBound" : 200000,
"upperBound" : 400000
}, {
"color" : "00716b",
"lowerBound" : 400000,
"upperBound" : 600000
} ]
} ],
"showPercentages" : true,
"showTotal" : true
},
98
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
"visualizationType" : "Gauge"
},
"reportId" : "00OR0000000K2UeMAK",
"title" : null,
"type" : "Report"
}, {
"componentData" : 1,
"footer" : null,
"header" : "Pipeline by Industry",
"id" : "01aR00000005aT5IAI",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
} ],
"autoSelectColumns" : false,
"filterColumns" : [ ],
"groupings" : [ {
"name" : "INDUSTRY"
} ],
"maxRows" : null,
"sort" : {
"column" : "INDUSTRY",
"sortOrder" : "asc"
},
"useReportChart" : false,
"visualizationProperties" : {
"combineSmallGroups" : false,
"legendPosition" : "Bottom",
"showPercentages" : false,
"showTotal" : false,
"showValues" : false
},
"visualizationType" : "Donut"
},
"reportId" : "00OR0000000OgsOMAS",
"title" : null,
"type" : "Report"
} ],
"description" : null,
"developerName" : "yTtOilrkFGewFKpFUOscDuukUApfxH",
"filters" : [ ],
"folderId" : "00lR0000000DnRZIA0",
"id" : "01ZR00000008h2EMAQ",
"layout" : {
"components" : [ {
"colspan" : 3,
"column" : 0,
"row" : 0,
"rowspan" : 4
}, {
"colspan" : 3,
"column" : 0,
"row" : 4,
"rowspan" : 4
99
Return Details About Dashboard ComponentsExamples: Dashboards REST API Resources
} ],
"gridLayout" : true,
"numColumns" : 9,
"rowHeight" : 80
},
"name" : "Liz's Sales Manager Dashboard",
"runningUser" : {
"displayName" : "Vandelay Art",
"id" : "005R0000000Hv5rIAC"
}
}
}
Get Dashboard Metadata
Get details about dashboard metadata using a GET request.
Use a GET request on the Dashboard Describe resource to get metadata for the specified dashboard, including dashboard components,
filters, layout, and the running user.
Example Usage
/services/data/v37.0/analytics/dashboards/01ZR00000004SknMAE/describe
Example Response Body
{
"canChangeRunningUser" : true,
"components" : [ {
"componentData" : 0,
"footer" : null,
"header" : null,
"id" : "01aR00000005kCmIAI",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
} ],
"autoSelectColumns" : true,
"filterColumns" : [ {
"label" : "Closed",
"name" : "CLOSED"
}, {
"label" : "Account Type",
"name" : "ACCOUNT_TYPE"
}, {
"label" : "Annual Revenue",
"name" : "SALES"
} ],
"groupings" : [ {
"name" : "STAGE_NAME"
} ],
"maxRows" : null,
"sort" : {
"column" : "STAGE_NAME",
100
Get Dashboard MetadataExamples: Dashboards REST API Resources
"sortOrder" : "asc"
},
"useReportChart" : false,
"visualizationProperties" : {
"axisRange" : {
"max" : null,
"min" : null,
"rangeType" : "auto"
},
"groupByType" : "cumulative",
"legendPosition" : "Bottom",
"showValues" : false
},
"visualizationType" : "Line"
},
"reportId" : "00OR0000000JizXMAS",
"title" : null,
"type" : "Report"
}, {
"componentData" : 1,
"footer" : null,
"header" : null,
"id" : "01aR00000005awVIAQ",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
} ],
"autoSelectColumns" : true,
"filterColumns" : [ {
"label" : "Closed",
"name" : "CLOSED"
}, {
"label" : "Account Type",
"name" : "ACCOUNT_TYPE"
}, {
"label" : "Annual Revenue",
"name" : "SALES"
} ],
"groupings" : [ {
"name" : "STAGE_NAME"
} ],
"maxRows" : null,
"sort" : {
"column" : "STAGE_NAME",
"sortOrder" : "asc"
},
"useReportChart" : false,
"visualizationProperties" : {
"combineSmallGroups" : true,
"legendPosition" : "Bottom",
"showPercentages" : false,
"showValues" : true
},
"visualizationType" : "Funnel"
101
Get Dashboard MetadataExamples: Dashboards REST API Resources
},
"reportId" : "00OR0000000OFXeMAO",
"title" : null,
"type" : "Report"
}, {
"componentData" : 2,
"footer" : null,
"header" : null,
"id" : "01aR00000005awTIAQ",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
} ],
"autoSelectColumns" : true,
"filterColumns" : [ {
"label" : "Closed",
"name" : "CLOSED"
}, {
"label" : "Account Type",
"name" : "ACCOUNT_TYPE"
}, {
"label" : "Annual Revenue",
"name" : "SALES"
} ],
"groupings" : null,
"maxRows" : null,
"sort" : null,
"useReportChart" : false,
"visualizationProperties" : {
"breakPoints" : [ {
"aggregateName" : "s!AMOUNT",
"breaks" : [ {
"color" : "c25454",
"lowerBound" : 100000,
"upperBound" : 300000
}, {
"color" : "c2c254",
"lowerBound" : 300000,
"upperBound" : 800000
}, {
"color" : "54c254",
"lowerBound" : 800000,
"upperBound" : 1000000
} ]
} ],
"showPercentages" : false,
"showTotal" : false
},
"visualizationType" : "Gauge"
},
"reportId" : "00OR0000000JizXMAS",
"title" : null,
"type" : "Report"
}, {
102
Get Dashboard MetadataExamples: Dashboards REST API Resources
"componentData" : 3,
"footer" : null,
"header" : null,
"id" : "01aR00000005kCnIAI",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
}, {
"name" : "a!AMOUNT"
} ],
"autoSelectColumns" : false,
"filterColumns" : [ {
"label" : "Closed",
"name" : "CLOSED"
}, {
"label" : "Account Type",
"name" : "ACCOUNT_TYPE"
}, {
"label" : "Annual Revenue",
"name" : "SALES"
} ],
"groupings" : [ {
"name" : "STAGE_NAME"
}, {
"name" : "TYPE"
} ],
"maxRows" : null,
"sort" : {
"column" : "STAGE_NAME",
"sortOrder" : "asc"
},
"useReportChart" : false,
"visualizationProperties" : {
"axisRange" : {
"max" : null,
"min" : null,
"rangeType" : "auto"
},
"groupByType" : "grouped",
"legendPosition" : "Bottom"
},
"visualizationType" : "Scatter"
},
"reportId" : "00OR0000000JizXMAS",
"title" : null,
"type" : "Report"
}, {
"componentData" : 4,
"footer" : null,
"header" : "My Table",
"id" : "01aR00000005awUIAQ",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
103
Get Dashboard MetadataExamples: Dashboards REST API Resources
} ],
"autoSelectColumns" : false,
"filterColumns" : [ {
"label" : "Closed",
"name" : "CLOSED"
}, {
"label" : "Account Type",
"name" : "ACCOUNT_TYPE"
}, {
"label" : "Annual Revenue",
"name" : "SALES"
} ],
"groupings" : [ {
"name" : "INDUSTRY"
}, {
"name" : "CLOSE_DATE"
} ],
"maxRows" : null,
"sort" : {
"column" : "INDUSTRY",
"sortOrder" : "asc"
},
"useReportChart" : false,
"visualizationProperties" : {
"breakPoints" : [ {
"aggregateName" : "s!AMOUNT",
"breaks" : [ {
"color" : "c25454",
"lowerBound" : null,
"upperBound" : null
}, {
"color" : "c2c254",
"lowerBound" : null,
"upperBound" : null
}, {
"color" : "54c254",
"lowerBound" : null,
"upperBound" : null
} ]
} ],
"tableColumns" : [ {
"column" : "INDUSTRY",
"isPercent" : false,
"scale" : null,
"showTotal" : false,
"type" : "grouping"
}, {
"column" : "CLOSE_DATE",
"isPercent" : false,
"scale" : null,
"showTotal" : false,
"type" : "grouping"
}, {
"column" : "s!AMOUNT",
104
Get Dashboard MetadataExamples: Dashboards REST API Resources
"isPercent" : false,
"scale" : null,
"showTotal" : true,
"type" : "aggregate"
} ]
},
"visualizationType" : "Table"
},
"reportId" : "00OR0000000OgsOMAS",
"title" : "My Table",
"type" : "Report"
}, {
"componentData" : 5,
"footer" : null,
"header" : null,
"id" : "01aR00000005kCoIAI",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
} ],
"autoSelectColumns" : false,
"filterColumns" : [ {
"label" : "Closed",
"name" : "CLOSED"
}, {
"label" : "Account Type",
"name" : "ACCOUNT_TYPE"
}, {
"label" : "Annual Revenue",
"name" : "SALES"
} ],
"groupings" : [ {
"name" : "STAGE_NAME"
}, {
"name" : "TYPE"
} ],
"maxRows" : null,
"sort" : {
"column" : "STAGE_NAME",
"sortOrder" : "asc"
},
"useReportChart" : false,
"visualizationProperties" : {
"aggregateVisualizationInfos" : [ {
"axis" : "Y2",
"visualizationType" : "Column"
} ],
"axisRange" : {
"max" : null,
"min" : null,
"rangeType" : "auto"
},
"groupByType" : "grouped",
"legendPosition" : "Bottom",
105
Get Dashboard MetadataExamples: Dashboards REST API Resources
"showValues" : false
},
"visualizationType" : "Column"
},
"reportId" : "00OR0000000JizXMAS",
"title" : null,
"type" : "Report"
}, {
"componentData" : 6,
"footer" : null,
"header" : null,
"id" : "01aR00000005kCpIAI",
"properties" : {
"aggregates" : [ {
"name" : "s!AMOUNT"
}, {
"name" : "a!AMOUNT"
} ],
"autoSelectColumns" : false,
"filterColumns" : [ {
"label" : "Closed",
"name" : "CLOSED"
}, {
"label" : "Account Type",
"name" : "ACCOUNT_TYPE"
}, {
"label" : "Annual Revenue",
"name" : "SALES"
} ],
"groupings" : [ {
"name" : "STAGE_NAME"
} ],
"maxRows" : null,
"sort" : {
"column" : "STAGE_NAME",
"sortOrder" : "asc"
},
"useReportChart" : false,
"visualizationProperties" : {
"axisRange" : {
"max" : null,
"min" : null,
"rangeType" : "auto"
},
"groupByType" : "none",
"legendPosition" : "Bottom",
"showValues" : false
},
"visualizationType" : "Bar"
},
"reportId" : "00OR0000000JizXMAS",
"title" : null,
"type" : "Report"
} ],
106
Get Dashboard MetadataExamples: Dashboards REST API Resources
"description" : null,
"developerName" : "Filtered_Dashboard",
"filters" : [ {
"errorMessage" : null,
"id" : "0IBR00000004CElOAM",
"name" : "Closed",
"options" : [ {
"alias" : "Open",
"endValue" : null,
"id" : "0ICR00000004CG4OAM",
"operation" : "equals",
"startValue" : null,
"value" : "True"
}, {
"alias" : "Closed",
"endValue" : null,
"id" : "0ICR00000004CG5OAM",
"operation" : "equals",
"startValue" : null,
"value" : "False"
} ],
"selectedOption" : null
}, {
"errorMessage" : null,
"id" : "0IBR00000004CEmOAM",
"name" : "Account Type",
"options" : [ {
"alias" : null,
"endValue" : null,
"id" : "0ICR00000004CG6OAM",
"operation" : "equals",
"startValue" : null,
"value" : "Analyst"
}, {
"alias" : null,
"endValue" : null,
"id" : "0ICR00000004CG7OAM",
"operation" : "equals",
"startValue" : null,
"value" : "Competitor"
}, {
"alias" : null,
"endValue" : null,
"id" : "0ICR00000004CG8OAM",
"operation" : "equals",
"startValue" : null,
"value" : "Press,Prospect,Reseller"
}, {
"alias" : null,
"endValue" : null,
"id" : "0ICR00000004CG9OAM",
"operation" : "notEqual",
"startValue" : null,
"value" : "Other"
107
Get Dashboard MetadataExamples: Dashboards REST API Resources
}, {
"alias" : "Outsiders",
"endValue" : null,
"id" : "0ICR00000004CGAOA2",
"operation" : "lessOrEqual",
"startValue" : null,
"value" : "Integrator,Partner,Prospect"
} ],
"selectedOption" : null
}, {
"errorMessage" : null,
"id" : "0IBR0000000007cOAA",
"name" : "Annual Revenue",
"options" : [ {
"alias" : null,
"endValue" : null,
"id" : "0ICR000000000A5OAI",
"operation" : "lessThan",
"startValue" : null,
"value" : "\"400,000\""
} ],
"selectedOption" : null
} ],
"folderId" : "00lR0000000DnRZIA0",
"id" : "01ZR00000004SknMAE",
"layout" : {
"columns" : [ {
"components" : [ 0, 1, 2 ]
}, {
"components" : [ 3, 4 ]
}, {
"components" : [ 5, 6 ]
} ],
"gridLayout" : false
},
"name" : "Filtered Dashboard",
"runningUser" : {
"displayName" : "Vandelay Art",
"id" : "005R0000000Hv5rIAC"
}
}
Clone a Dashboard
Creates a copy of a dashboard by sending a POST request to the Dashboard List resource.
Example
You want to clone dashboard 01ZR00000008gkvMAA and save it in a new folder with ID 00lR0000000DnRZIA0.
108
Clone a DashboardExamples: Dashboards REST API Resources
This POST request /services/data/v35.0/analytics/dashboards/?cloneId=01ZR00000008gkvMAA to the
Dashboard List resource clones the dashboard.
{"folderId":"00lR0000000DnRZIA0"}
The response to the POST request returns the following details about the cloned dashboard.
{ "attributes" :
{ "dashboardId" : "01ZR00000004SZZMA2",
"dashboardName" : "Sales Manager Dashboard",
"statusUrl" : "/services/data/v35.0/analytics/dashboards/01ZR00000004SZZMA2/status",
"type" : "Dashboard" },
...
"folderId" : "00lR0000000DnRZIA0",
"id" : "01ZR00000004SZZMA2",
"layout" : {
"columns" : [
{ "components" : [ 0, 1, 2, 3 ] },
{ "components" : [ 4, 5, 6 ] },
{ "components" : [ 7 ] } ],
"gridLayout" : false },
"name" : "Sales Manager Dashboard",
"runningUser" : { "displayName" : "Fred Wiliamson", "id" : "005R0000000Hv5rIAC" }
}
Delete a Dashboard
Delete a dashboard by sending a DELETE request to the Dashboard Results resource. Deleted dashboards are moved to the Recycle Bin.
Example
This DELETE request /services/data/v34.0/analytics/dashboards/01ZD00000007S89MAE to the Dashboard
Results resource deletes the dashboard and returns a 204 HTTP response code with no content in the response body.
109
Delete a DashboardExamples: Dashboards REST API Resources
CHAPTER 4 Examples: Analytics Notifications REST API
Use the Analytics Notifications REST API to get, update, create, and delete notifications about reports
and Wave assets.
In this chapter ...
•Get Analytics
Notifications
•Create an Analytics
Notification
•Save Changes to an
Analytics Notification
•Delete an Analytics
Notification
•Check Limits for
Analytics
Notifications
110
Get Analytics Notifications
Return a list of analytics notifications using a GET request.
Use a GET request on the Analytics Notification List resource to return a list of analytics notifications.
Example Usage
/services/data/v38.0/analytics/notifications?source=lightningSubscribe
DescriptionParameter
Required for GET calls. Specifies what type of analytics notification to return. Valid values are:source
•lightningSubscribe — report subscriptions
•waveNotification — Wave notifications
Optional. Return notifications for a single record. Valid values are:recordId
•reportId— Unique report ID
•lensId— Unique Wave lens ID
Example Response Body
[ {
"active" : true,
"createdDate" : "2016-08-08T04:14:12Z",
"deactivateOnTrigger" : false,
"id" : "0AuR00000004CYpKAM",
"lastModifiedDate" : "2016-08-08T04:14:12Z",
"name" : "Notification1",
"recordId" : "00OR0000000P7EgMAK",
"schedule" : {
"details" : {
"time" : 3
},
"frequency" : "daily"
},
"source" : "lightningSubscribe",
"thresholds" : [ {
"actions" : [ {
"configuration" : {
"recipients" : [ ]
},
"type" : "sendEmail"
} ],
"conditions" : null,
"type" : "always"
} ]
}, {
"active" : true,
"createdDate" : "2016-08-10T22:22:17Z",
"deactivateOnTrigger" : false,
"id" : "0AuR000000000KSKAY",
111
Get Analytics NotificationsExamples: Analytics Notifications REST API
"lastModifiedDate" : "2016-08-11T23:16:01Z",
"name" : "Notification2",
"recordId" : "00OR0000000PCHYMA4",
"schedule" : {
"details" : {
"daysOfMonth" : [ 1, 2, 4 ],
"time" : 22
},
"frequency" : "monthly",
"frequencyType" : "specific"
},
"source" : "lightningSubscribe",
"thresholds" : [ {
"actions" : [ {
"configuration" : {
"recipients" : [ ]
},
"type" : "sendEmail"
} ],
"conditions" : null,
"type" : "always"
} ]
}, {
"active" : true,
"createdDate" : "2016-08-12T04:01:50Z",
"deactivateOnTrigger" : false,
"id" : "0AuR000000000KcKAI",
"lastModifiedDate" : "2016-08-12T04:16:34Z",
"name" : "Notification3",
"recordId" : "00OR0000000PBXEMA4",
"schedule" : {
"details" : {
"dayInWeek" : "mon",
"time" : 22,
"weekInMonth" : "third"
},
"frequency" : "monthly",
"frequencyType" : "relative"
},
"source" : "lightningSubscribe",
"thresholds" : [ {
"actions" : [ {
"configuration" : {
"recipients" : [ ]
},
"type" : "sendEmail"
} ],
"conditions" : null,
"type" : "always"
} ]
} ]
112
Get Analytics NotificationsExamples: Analytics Notifications REST API
Create an Analytics Notification
Create an Analytics Notification using a POST request.
Use a POST request on the Analytics Notification List resource to create an analytics notification.
Example Usage
/services/data/v38.0/analytics/notifications
Example Request Body
{
"active" : true,
"createdDate" : "",
"deactivateOnTrigger" : false,
"id" : "",
"lastModifiedDate" : "",
"name" : "New Notification",
"recordId" : "00OR0000000PD55MAG",
"schedule" : {
"details" : {
"time" : 3
},
"frequency" : "daily"
},
"source" : "lightningSubscribe",
"thresholds" : [ {
"actions" : [ {
"configuration" : {
"recipients" : [ ]
},
"type" : "sendEmail"
} ],
"conditions" : null,
"type" : "always"
} ]
}
Example Response Body
{
"active" : true,
"createdDate" : "2016-08-12T05:57:19Z",
"deactivateOnTrigger" : false,
"id" : "0AuR00000004CZTKA2",
"lastModifiedDate" : "2016-08-12T05:57:19Z",
"name" : "New Notification",
"recordId" : "00OR0000000PD55MAG",
"schedule" : {
"details" : {
"time" : 3
},
"frequency" : "daily"
},
"source" : "lightningSubscribe",
"thresholds" : [ {
113
Create an Analytics NotificationExamples: Analytics Notifications REST API
"actions" : [ {
"configuration" : {
"recipients" : [ ]
},
"type" : "sendEmail"
} ],
"conditions" : null,
"type" : "always"
} ]
}
Save Changes to an Analytics Notification
Save Changes to an Analytics Notification using a PUT request.
Use a PUT request on the Analytics Notification resource to save changes to an analytics notification.
Example Usage
/services/data/v38.0/analytics/notifications/analytics notification ID
Example Request Body
In this example, an analytics notification is changed so that it runs daily at 9:00 AM instead of 3:00 AM.
{
"active" : true,
"createdDate" : "",
"deactivateOnTrigger" : false,
"id" : "0AuR00000004CZTKA2",
"lastModifiedDate" : "",
"name" : "New Notification",
"recordId" : "00OR0000000PD55MAG",
"schedule" : {
"details" : {
"time" : 9
},
"frequency" : "daily"
},
"source" : "lightningSubscribe",
"thresholds" : [ {
"actions" : [ {
"configuration" : {
"recipients" : [ ]
},
"type" : "sendEmail"
} ],
"conditions" : null,
"type" : "always"
} ]
}
114
Save Changes to an Analytics NotificationExamples: Analytics Notifications REST API
Example Response Body
The response body reflects the updated and saved analytics notifications.
{
"active" : true,
"createdDate" : "2016-08-12T05:57:19Z",
"deactivateOnTrigger" : false,
"id" : "0AuR00000004CZTKA2",
"lastModifiedDate" : "2016-08-12T06:12:24Z",
"name" : "New Notification",
"recordId" : "00OR0000000PD55MAG",
"schedule" : {
"details" : {
"time" : 9
},
"frequency" : "daily"
},
"source" : "lightningSubscribe",
"thresholds" : [ {
"actions" : [ {
"configuration" : {
"recipients" : [ ]
},
"type" : "sendEmail"
} ],
"conditions" : null,
"type" : "always"
} ]
}
Delete an Analytics Notification
Delete an Analytics Notification using a DELETE request. Once deleted, the analytics notification can't be recovered.
Use a DELETE request on the Analytics Notification resource to delete an analytics notification.
Example Usage
/services/data/v38.0/analytics/notifications/analytics notification ID
The analytic notification deletes and returns a 204 HTTP response code with no content in the response body.
Check Limits for Analytics Notifications
Check analytics notification limits using a GET request.
Use a GET request on the Analytics Notification Limits resource to check limits for analytics notifications.
Example Usage
/services/data/v38.0/analytics/notifications/limits?source=waveNotification
DescriptionMethod
Check how many analytic notifications you have, and the maximum number you can have.GET
115
Delete an Analytics NotificationExamples: Analytics Notifications REST API
Example Response Body
{
"userLimit" : {
"max" : 5,
"remaining" : 2
}
}
116
Check Limits for Analytics NotificationsExamples: Analytics Notifications REST API
CHAPTER 5 Reports API Resource Reference
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.
In this chapter ...
•Report
•Describe
DescriptionSupported
HTTP
Method
Resource
•Execute Sync
•Execute Async
•Instances List
Saves changes to a report.PATCH
Report
•Instance Results
•Report List Deletes a report.DELETE
•Query
Gives report metadata. This includes information about fields that
are defined in the report as detail columns, summaries, custom
summary formulas, filters, and groupings.
GETDescribe
•Report Error Codes
Gives report summary level data with or without details.GET
Execute Sync
Returns specific results if you define dynamic filters, groupings, or
aggregates in the metadata of a POST request.
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.
POSTExecute Async
List of instances of a report that were requested for an
asynchronous run.
GETInstances List
Depending on the type of your request, gives summary level data
with or without details for an instance of a report run
asynchronously.
GETInstance Results
List of reports that were recently viewed by the API user.GET
Report List
Makes a copy of a report.POST
117
Report
Saves changes to a report or deletes a report.
Resource URL
URLData
/services/data/<latest API version>/analytics/reports/<report ID>
Summary
Formats
JSON
HTTP Methods
DescriptionMethod
Saves changes to a report. See this example.PATCH
Deletes a report. See this example.DELETE
PATCH Request Body
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
137[]
crossFilters
118
ReportReports API Resource Reference
DescriptionTypeProperty
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
Report API name.StringdeveloperName
Determines the division of records to include in the report. For example,
West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data and
you have the “Affected by Divisions” permission. If you do not have the
“Affected by Divisions” permission, your reports include records in all
divisions.
ID of the folder that contains the report.StringfolderId
Note: When the report is in the My Personal Custom Reports
folder, folderId = userId. When the report is in the Unfiled Public
Reports folder, folderId = orgId.
Unique identities for each column grouping in a report. The identity is:Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
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
StringreportBooleanFilter
119
ReportReports API Resource Reference
DescriptionTypeProperty
exceeds 100K AND they are medium or large sized businesses. The
filters are processed by the logic, “(1 OR 2) AND 3.”
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
Defines the scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities you own,
Stringscope
or opportunities your team owns. Valid values depend on the report
type.
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
120
ReportReports API Resource Reference
DescriptionTypeProperty
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
startDate: Start date.
endDate: End date.
List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
Array of stringsstandardFilters
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering (true)
or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
PATCH Response Body
DescriptionTypeProperty
Unique identifiers for groupings and summaries.Report metadatareportMetadata
Fields in each section of a report type plus filter information for those
fields.
Report type metadatareportTypeMetadata
Additional information about summaries and groupings.Report extended
metadata
reportExtendedMetadata
Report metadata
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
121
ReportReports API Resource Reference
DescriptionTypeProperty
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity
is a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
128[]
crossFilters
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
Report API name.StringdeveloperName
Determines the division of records to include in the report. For
example, West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data
and you have the “Affected by Divisions” permission. If you do not
have the “Affected by Divisions” permission, your reports include
records in all divisions.
ID of the folder that contains the report.StringfolderId
Note: When the report is in the My Personal Custom Reports
folder, folderId = userId. When the report is in the Unfiled
Public Reports folder, folderId = orgId.
Unique identities for each column grouping in a report. The identity
is:
Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
122
ReportReports API Resource Reference
DescriptionTypeProperty
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
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
StringreportBooleanFilter
revenue exceeds 100K AND they are medium or large sized
businesses. The filters are processed by the logic, “(1 OR 2) AND 3.”
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
123
ReportReports API Resource Reference
DescriptionTypeProperty
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
Defines the scope of the data on which you run the report. For
example, you can run the report against all opportunities,
Stringscope
opportunities you own, or opportunities your team owns. Valid values
depend on the report type.
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
startDate: Start date.
endDate: End date.
List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the
Array of stringsstandardFilters
Opportunity object are Show, Opportunity Status, and Probability.
This list appears as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering
(true) or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
124
ReportReports API Resource Reference
Chart
DescriptionTypeProperty
Type of chart.StringchartType
Report grouping.Stringgroupings
Indicates whether the report has a legend.BooleanhasLegend
Indicates whether the report shows chart values.BooleanshowChartValues
Unique identities for summary or custom summary formula fields
in the report. For example:
Array of stringssummaries
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom
field column. For custom fields and custom report types, the
identity is a combination of the summary type and the field ID.
Specifies the axis that shows the summary values. Valid values are
X and Y.
StringsummaryAxisLocations
Name of the chart.Stringtitle
Groupings down
DescriptionTypeProperty
API name of the field used as a row grouping.Stringname
Order in which data is sorted within a row grouping. Value can be:StringsortOrder
•Asc for ascending order.
•Desc for descending order.
Interval set on a date field that’s used as a row grouping. Value can
be:
StringdateGranularity
•Day
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
125
ReportReports API Resource Reference
DescriptionTypeProperty
•Calendar Month in Year
•Calendar Day in Month
Summary field that’s used to sort data within a grouping in a report
that’s in summary format. Applies if you have the Aggregate Sort
StringsortAggregate
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
DescriptionTypeProperty
API name of the field used as a column grouping.Stringname
Order in which data is sorted within a column grouping. Value can
be:
StringsortOrder
•Asc for ascending order.
•Desc for descending order.
Interval set on a date field used as a column grouping. Value can
be:
StringdateGranularity
•Day
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
•Calendar Month in Year
•Calendar Day in Month
126
ReportReports API Resource Reference
Filter details
DescriptionTypeProperty
Unique API name for the field that’s being filtered.Stringcolumn
Indicates if this is an editable filter in the user interface.BooleanisRunPageEditable
Unique API name for the condition used to filter a field such as
“greater than” or “not equal to.” Filter conditions depend on the
data type of the field. Valid values are:
Stringoperator
•equals
•notEqual
•lessThan
•greaterThan
•lessOrEqual
•greaterOrEqual
•contains
•notContain
•startsWith
•includes
•excludes
•within (DISTANCE criteria only)
Value by which a field is filtered. For example, the field Age can
be filtered by a numeric value.
For datetime fields, if you make a POST request and specify a
calendar date without including a time, then a default time gets
Stringvalue
included. The time defaults to midnight minus the difference
between your timezone and Greenwich Mean Time (GMT). For
example, if you specify 8/8/2015 and your timezone is Pacific
Standard Time (GMT-700), then the API returns
2015-08-08T07:00:00Z.
Bucket field
DescriptionTypeProperty
The type of bucket. Possible values are number, percent, and
picklist
BucketTypebucketType
API name of the bucket.StringdeveloperName
User-facing name of the bucket.Stringlabel
Specifies whether null values are converted to zero (true) or not
(false).
BooleannullTreatedAsZero
127
ReportReports API Resource Reference
DescriptionTypeProperty
Name of the fields grouped as “Other” (in buckets of BucketType
PICKLIST).
StringotherBucketLabel
Name of the bucketed field.StringsourceColumnName
Describes the values included in the bucket field..Array of
BucketTypeValues
values
Bucket field value
DescriptionTypeProperty
The user-facing name of the bucket.Stringlabel
A list of the values from the source field included in this bucket
category (in buckets of type PICKLIST and buckets of type TEXT).
StringsourceDimensionValues
The greatest range limit under which values are included in this
bucket category (in buckets of type NUMBER).
DoublerangeUpperBound
Cross filter
DescriptionTypeProperty
Information about how to filter the relatedEntity. Use to relate
the primary entity with a subset of the relatedEntity.
Array of Filter details[]criteria
Specifies whether objects returned have a relationship with the
relatedEntity (true) or not (false).
BooleanincludesObject
The name of the object on which the cross filter is evaluated.StringprimaryEntityField
The name of the object that the primaryEntityField is
evaluated against. (The right-hand side of the cross filter).
StringrelatedEntity
The name of the field used to join the primaryEntityField
and relatedEntity.
StringrelatedEntityJoinField
Custom summary formula
DescriptionTypeProperty
The user-facing name of the custom summary formula.Stringlabel
The user-facing description of the custom summary formula.Stringdescription
The format of the numbers in the custom summary formula. Possible
values are number, currency, and percent.
StringformulaType
The number of decimal places to include in numbers.IntegerdecimalPlaces
128
ReportReports API Resource Reference
DescriptionTypeProperty
The name of a row grouping when the downGroupType is
CUSTOM. Null otherwise.
StringdownGroup
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringdownGroupType
The name of a column grouping when the accrossGroupType
is CUSTOM. Null otherwise.
StringacrossGroup
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringacrossGroupType
The operations performed on values in the custom summary formula.Stringformula
Top rows
DescriptionTypeProperty
The number of rows returned in the report.IntegerrowLimit
The sort order of the report rows.Stringdirection
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
DescriptionMethod
Retrieves report, report type, and related metadata for a tabular, summary, or matrix report. See this example.GET
129
DescribeReports API Resource Reference
Response Body
DescriptionTypeProperty
Unique identifiers for groupings and summaries.Report metadatareportMetadata
Fields in each section of a report type plus filter information for those
fields.
Report type metadatareportTypeMetadata
Additional information about summaries and groupings.Report extended
metadata
reportExtendedMetadata
Report metadata
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity
is a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
137[]
crossFilters
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
Report API name.StringdeveloperName
Determines the division of records to include in the report. For
example, West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data
and you have the “Affected by Divisions” permission. If you do not
130
DescribeReports API Resource Reference
DescriptionTypeProperty
have the “Affected by Divisions” permission, your reports include
records in all divisions.
ID of the folder that contains the report.StringfolderId
Note: When the report is in the My Personal Custom Reports
folder, folderId = userId. When the report is in the Unfiled
Public Reports folder, folderId = orgId.
Unique identities for each column grouping in a report. The identity
is:
Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
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
StringreportBooleanFilter
revenue exceeds 100K AND they are medium or large sized
businesses. The filters are processed by the logic, “(1 OR 2) AND 3.”
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{
131
DescribeReports API Resource Reference
DescriptionTypeProperty
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
Defines the scope of the data on which you run the report. For
example, you can run the report against all opportunities,
Stringscope
opportunities you own, or opportunities your team owns. Valid values
depend on the report type.
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
startDate: Start date.
endDate: End date.
132
DescribeReports API Resource Reference
DescriptionTypeProperty
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
Array of stringsstandardFilters
Opportunity object are Show, Opportunity Status, and Probability.
This list appears as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering
(true) or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
Chart
DescriptionTypeProperty
Type of chart.StringchartType
Report grouping.Stringgroupings
Indicates whether the report has a legend.BooleanhasLegend
Indicates whether the report shows chart values.BooleanshowChartValues
Unique identities for summary or custom summary formula fields
in the report. For example:
Array of stringssummaries
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom
field column. For custom fields and custom report types, the
identity is a combination of the summary type and the field ID.
Specifies the axis that shows the summary values. Valid values are
X and Y.
StringsummaryAxisLocations
Name of the chart.Stringtitle
133
DescribeReports API Resource Reference
Groupings down
DescriptionTypeProperty
API name of the field used as a row grouping.Stringname
Order in which data is sorted within a row grouping. Value can be:StringsortOrder
•Asc for ascending order.
•Desc for descending order.
Interval set on a date field that’s used as a row grouping. Value can
be:
StringdateGranularity
•Day
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
•Calendar Month in Year
•Calendar Day in Month
Summary field that’s used to sort data within a grouping in a report
that’s in summary format. Applies if you have the Aggregate Sort
StringsortAggregate
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
DescriptionTypeProperty
API name of the field used as a column grouping.Stringname
134
DescribeReports API Resource Reference
DescriptionTypeProperty
Order in which data is sorted within a column grouping. Value can
be:
StringsortOrder
•Asc for ascending order.
•Desc for descending order.
Interval set on a date field used as a column grouping. Value can
be:
StringdateGranularity
•Day
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
•Calendar Month in Year
•Calendar Day in Month
Filter details
DescriptionTypeProperty
Unique API name for the field that’s being filtered.Stringcolumn
Indicates if this is an editable filter in the user interface.BooleanisRunPageEditable
Unique API name for the condition used to filter a field such as
“greater than” or “not equal to.” Filter conditions depend on the
data type of the field. Valid values are:
Stringoperator
•equals
•notEqual
•lessThan
•greaterThan
•lessOrEqual
•greaterOrEqual
•contains
•notContain
•startsWith
•includes
•excludes
•within (DISTANCE criteria only)
135
DescribeReports API Resource Reference
DescriptionTypeProperty
Value by which a field is filtered. For example, the field Age can
be filtered by a numeric value.
For datetime fields, if you make a POST request and specify a
calendar date without including a time, then a default time gets
Stringvalue
included. The time defaults to midnight minus the difference
between your timezone and Greenwich Mean Time (GMT). For
example, if you specify 8/8/2015 and your timezone is Pacific
Standard Time (GMT-700), then the API returns
2015-08-08T07:00:00Z.
Bucket field
DescriptionTypeProperty
The type of bucket. Possible values are number, percent, and
picklist
BucketTypebucketType
API name of the bucket.StringdeveloperName
User-facing name of the bucket.Stringlabel
Specifies whether null values are converted to zero (true) or not
(false).
BooleannullTreatedAsZero
Name of the fields grouped as “Other” (in buckets of BucketType
PICKLIST).
StringotherBucketLabel
Name of the bucketed field.StringsourceColumnName
Describes the values included in the bucket field..Array of
BucketTypeValues
values
Bucket field value
DescriptionTypeProperty
The user-facing name of the bucket.Stringlabel
A list of the values from the source field included in this bucket
category (in buckets of type PICKLIST and buckets of type TEXT).
StringsourceDimensionValues
The greatest range limit under which values are included in this
bucket category (in buckets of type NUMBER).
DoublerangeUpperBound
136
DescribeReports API Resource Reference
Cross filter
DescriptionTypeProperty
Information about how to filter the relatedEntity. Use to relate
the primary entity with a subset of the relatedEntity.
Array of Filter details[]criteria
Specifies whether objects returned have a relationship with the
relatedEntity (true) or not (false).
BooleanincludesObject
The name of the object on which the cross filter is evaluated.StringprimaryEntityField
The name of the object that the primaryEntityField is
evaluated against. (The right-hand side of the cross filter).
StringrelatedEntity
The name of the field used to join the primaryEntityField
and relatedEntity.
StringrelatedEntityJoinField
Custom summary formula
DescriptionTypeProperty
The user-facing name of the custom summary formula.Stringlabel
The user-facing description of the custom summary formula.Stringdescription
The format of the numbers in the custom summary formula. Possible
values are number, currency, and percent.
StringformulaType
The number of decimal places to include in numbers.IntegerdecimalPlaces
The name of a row grouping when the downGroupType is
CUSTOM. Null otherwise.
StringdownGroup
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringdownGroupType
The name of a column grouping when the accrossGroupType
is CUSTOM. Null otherwise.
StringacrossGroup
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringacrossGroupType
The operations performed on values in the custom summary formula.Stringformula
Top rows
DescriptionTypeProperty
The number of rows returned in the report.IntegerrowLimit
The sort order of the report rows.Stringdirection
137
DescribeReports API Resource Reference
Report type metadata
DescriptionTypeProperty
All fields in the report type organized by section.Categories[]categories
Lists all the possible field data types that can be used to filter
the report. Each data type, such as phone, percent, currency,
or picklist has two properties:
name: Of type string, this is a unique API name for each field
type’s filter criteria. Use this API name in the metadata to
define filter criteria for a report.
Filter operator
reference
dataTypeFilterOperatorMap
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.
Default division and list of all possible record-level divisions
that can be used in a report.
Division info[]divisionInfo
Scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities
Scope info[]scopeInfo
you own, or opportunities your team owns. Valid values
depend on the report type.
List of standard date filters available in reports.Standard date filter
duration groups[]
standardDateFilterDurationGroups
List of filters that show up in the report by default. The filters
vary by report type. For example, standard filters for reports
Array of stringsstandardFilterInfos
on the Opportunity object are Show, Opportunity Status, and
Probability. This list appears as name-value string pairs.
Categories
DescriptionTypeProperty
Display name of a section in the report type under which fields are
organized. For example, in an Accounts with Contacts custom report
Stringlabel
type, Account General is the display name of the section that
has fields on general account information.
Information for all fields in the report type organized under a
particular section’s unique API name.
Column mapcolumns
138
DescribeReports API Resource Reference
Division info
DescriptionTypeProperty
Users are assigned a default division that applies to their newly
created accounts, leads, and custom objects that are enabled for
divisions.
StringdefaultValue
All division values. Division values have two properties:
label: Display name of a division.
Stringvalues
name: Unique API name of a division.
Column map
DescriptionTypeProperty
Display name of a field.Stringlabel
All filter values for a field, if the field data type is of picklist,
multi-select picklist, boolean, or checkbox. For example, checkbox
String arrayfilterValues
fields always have a value of True or False. For fields of other
data types, the filter value is an empty array because their values
can’t be determined. Filter values have two properties:
name: Unique API name for a filter value. Of type string.
label: Display name of a filter value. Of type string.
Data type of the field.StringdataType
False means that the field is of a type that can’t be filtered. For
example, fields of the type Encrypted Text can’t be filtered.
Booleanfilterable
Scope Info
DescriptionTypeProperty
Default scope of the data on which you run the report.StringdefaultValue
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.
Array of stringsvalues
label: Display name of the scope.
value: Value of the scope.
139
DescribeReports API Resource Reference
Standard date filter duration groups
DescriptionTypeProperty
Display name of the standard date filter grouping. Valid values
are Calendar Year, Calendar Quarter, Calendar Month, Calendar
Stringlabel
Week, Fiscal Year, Fiscal Quarter, Day and custom value based
on a user-defined date range.
Details about each possible relative date filter defined under
the standard date filter grouping.
Standard date filter
durations[]
standardDateFilterDurations
Standard date filter durations
DescriptionTypeProperty
End date of a date filter.StringendDate
Display name of a date filter. Valid date filters are relative date
filters—like Current FY and Current FQ—and custom
date filters.
Stringlabel
Start date of a date filter.StringstartDate
API name of a date filter. Valid date filters are relative date
filters—like THIS_FISCAL_YEAR and
NEXT_FISCAL_QUARTER—and custom date filters.
Stringvalue
Report extended metadata
DescriptionTypeProperty
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.
Aggregate column
information
aggregateColumnInfo
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.
Detail column
information
detailColumnInfo
Map of each row or column grouping to its metadata. Contains values
for each grouping identified in the groupingsDown and
groupingsAcross list.
Grouping column
information
groupingColumnInfo
Aggregate column information
DescriptionTypeProperty
Display name for record count, or the summarized or custom
summary formula field.
Stringlabel
140
DescribeReports API Resource Reference
DescriptionTypeProperty
Data type of the summarized or custom summary formula field.StringdataType
Column grouping in the report where the custom summary formula
is displayed. As this example shows in the JSON response and in
StringacrossGroupingContext
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"
},
}
}
}
Row grouping in the report where the custom summary formula
is displayed. In this example, the custom summary formula for a
StringdownGroupingContext
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"
},
}
}
}
141
DescribeReports API Resource Reference
DescriptionTypeProperty
Detail column information
DescriptionTypeProperty
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.
Stringlabel
The data type of the field that has detailed data. Possible values
are:
StringdataType
•string
•boolean
•double
•int
•percent
•currency
•date
•datetime
•time
•picklist
•multipicklist
•id
•reference
•textarea
•phone
•combobox
•url
•email
•html
Grouping column information
DescriptionTypeProperty
Display name of the field or bucket field used for grouping.Stringlabel
142
DescribeReports API Resource Reference
DescriptionTypeProperty
Data type of the field used for grouping. Possible values are:StringdataType
•string
•boolean
•double
•int
•percent
•currency
•date
•datetime
•time
•picklist
•multipicklist
•id
•reference
•textarea
•phone
•combobox
•url
•email
•html
Level of the grouping. Value can be:
IntegergroupingLevel
•0, 1, or 2. Indicates first, second, or third row level grouping
in summary reports.
•0 or 1. Indicates first or second row or column level grouping
in a matrix report.
SEE ALSO:
Execute Sync
Execute Async
Execute Sync
Runs a report immediately with or without changing filters, groupings, or aggregates and returns the latest summary data with or without
details for your level of access.
143
Execute SyncReports API Resource Reference
Resource URL
/services/data/<latest API version>/analytics/reports/<report ID>
Formats
JSON
HTTP Methods
DescriptionMethod
Get report results. See this example.GET
Get specific results by passing dynamic filters, groupings, and aggregates in the report metadata. See this example.POST
POST Request Body
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
137[]
crossFilters
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
144
Execute SyncReports API Resource Reference
DescriptionTypeProperty
Report API name.StringdeveloperName
Determines the division of records to include in the report. For example,
West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data and
you have the “Affected by Divisions” permission. If you do not have the
“Affected by Divisions” permission, your reports include records in all
divisions.
ID of the folder that contains the report.StringfolderId
Note: When the report is in the My Personal Custom Reports
folder, folderId = userId. When the report is in the Unfiled Public
Reports folder, folderId = orgId.
Unique identities for each column grouping in a report. The identity is:Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
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
StringreportBooleanFilter
exceeds 100K AND they are medium or large sized businesses. The
filters are processed by the logic, “(1 OR 2) AND 3.”
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
145
Execute SyncReports API Resource Reference
DescriptionTypeProperty
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
Defines the scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities you own,
Stringscope
or opportunities your team owns. Valid values depend on the report
type.
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
146
Execute SyncReports API Resource Reference
DescriptionTypeProperty
startDate: Start date.
endDate: End date.
List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
Array of stringsstandardFilters
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering (true)
or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
Response Body
DescriptionTypeProperty
Key report attributes and child resource URLs.Attributesattributes
When True, all report results are returned.
BooleanallData
When False, results are returned for the same number of rows as
a report run in Salesforce.
Note: For reports that have too many records, use filters to
refine results.
Summary level data or both summary and detailed data for each row
or column grouping. Detailed data is available if hasDetailRows
is true.
Each row or column grouping is represented by combination of row
and column grouping keys defined in Groupings down and
Groupings across.
Fact mapfactMap
See these examples of fact map keys.
Collection of column groupings, keys, and their values.Groupings acrossgroupingsAcross
Collection of row groupings, keys, and their values.Groupings downgroupingsDown
When true,the fact map returns values for both summary level
and record level data.
BooleanhasDetailRows
When false, the fact map returns summary values.
147
Execute SyncReports API Resource Reference
DescriptionTypeProperty
Additional information about columns, summaries, and groupings.Report extended
metadata
reportExtendedMetadata
Unique identifiers for groupings and summaries.Report metadatareportMetadata
Attributes
DescriptionTypeProperty
Resource URL to get report metadata.StringdescribeUrl
Resource URL to run a report asynchronously. The report can be
run with or without filters to get summary or both summary and
StringinstancesUrl
detailed data. Results of each instance of the report run are stored
under this URL.
API resource format.Stringtype
Display name of the report.StringreportName
Unique report ID.StringreportId
Fact map
DescriptionTypeProperty
Array of detailed report data listed in the order of the detail
columns provided by the report metadata.
Data cells[]rows
Summary level data including record count for a report.Aggregates[]aggregates
Data cells
DescriptionTypeProperty
The value of a specified cell.Detail column info
data type
value
Display name of the value as it appears for a specified cell in the
report.
Stringlabel
Aggregates
DescriptionTypeProperty
Numeric value of the summary data for a specified cell.Numbervalue
Formatted summary data for a specified cell.Stringlabel
148
Execute SyncReports API Resource Reference
Groupings across
DescriptionTypeProperty
Information for each column grouping as a list.Groupings[]groupings
Groupings
DescriptionTypeProperty
Value of the field used as a row or column grouping. The value
depends on the field’s data type.
Stringvalue
•Currency fields:
–amount: Of type currency. Value of a data cell.
–currency: Of type picklist. The ISO 4217 currency code,
if available; for example, USD for US dollars or CNY for
Chinese yuan. (If the grouping is on the converted
currency, this is the currency code for the report and not
for the record.)
•Picklist fields: API name. For example, a custom picklist field,
Type of Business with values 1, 2, 3 for Consulting,
Services, and Add-On Business, has 1, 2, or 3 as the grouping
value.
•ID fields: API name.
•Record type fields: API name.
•Date and time fields: Date or time in ISO-8601 format.
•Lookup fields: Unique API name. For example, for the
Opportunity Owner lookup field, the ID of each
opportunity owner’s Chatter profile page can be a grouping
value.
Unique identity for a row or column grouping. The identity is used
by the fact map to specify data values within each grouping.
Stringkey
Display name of a row or column grouping. For date and time
fields, the label is the localized date or time.
Stringlabel
Second or third level row or column groupings. If there are none,
the value is an empty array.
Arraygroupings
Start date and end date of the interval defined by date
granularity.
Arraydategroupings
149
Execute SyncReports API Resource Reference
Groupings down
DescriptionTypeProperty
Information for each row grouping as a list.Groupings[]groupings
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
DescriptionMethod
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
POST Request Body
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
150
Execute AsyncReports API Resource Reference
DescriptionTypeProperty
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
137[]
crossFilters
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
Report API name.StringdeveloperName
Determines the division of records to include in the report. For example,
West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data and
you have the “Affected by Divisions” permission. If you do not have the
“Affected by Divisions” permission, your reports include records in all
divisions.
ID of the folder that contains the report.StringfolderId
Note: When the report is in the My Personal Custom Reports
folder, folderId = userId. When the report is in the Unfiled Public
Reports folder, folderId = orgId.
Unique identities for each column grouping in a report. The identity is:Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
151
Execute AsyncReports API Resource Reference
DescriptionTypeProperty
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
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
StringreportBooleanFilter
exceeds 100K AND they are medium or large sized businesses. The
filters are processed by the logic, “(1 OR 2) AND 3.”
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
152
Execute AsyncReports API Resource Reference
DescriptionTypeProperty
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,
Stringscope
or opportunities your team owns. Valid values depend on the report
type.
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
startDate: Start date.
endDate: End date.
List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
Array of stringsstandardFilters
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering (true)
or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
Response Body
DescriptionTypeProperty
Unique ID for an instance of a report that was run asynchronously.Stringid
Stringstatus •New if the report run has just been triggered through a request.
•Success if the report ran.
•Running if the report is being run.
153
Execute AsyncReports API Resource Reference
DescriptionTypeProperty
•Error if the report run failed. The instance of a report run can return an error if, for
example, your permission to access the report has been removed since you requested
the run.
URL where results of the report run for that instance are stored. The value is null if the
report couldn’t be run because of an error.
Stringurl
API name of the user that created the instance.StringownerId
Date, time when the instance of the report run finished. Only available if the report instance
ran successfully or couldn’t be run because of an error. Date-time information is in ISO-8601
format.
Date, time
string
completionDate
BooleanhasDetailRows •When false, indicates that summary level data was requested for the report instance.
•When true, indicates that detailed data, which includes summary level data, was
requested for the report instance.
Date and time when an instance of the report run was requested. Date-time information
is in ISO-8601 format.
Date, time
string
requestDate
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
DescriptionMethod
Return a list of asynchronous runs of a report. See this example.GET
154
Instances ListReports API Resource Reference
Response Body
DescriptionTypeProperty
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.
Stringid
Stringstatus •New if the report run has just been triggered through a POST request.
•Success if the report ran.
•Running if the report is being run.
•Error if the report run failed. The instance of a report run can return an
error if, for example, your permission to access the report has been removed
since you requested the run.
URL where results of the report run for that instance are stored. The value is
null if the report couldn’t be run because of an error.
Stringurl
API name of the user that created the instance.StringownerId
BooleanhasDetailRows •When false, indicates that summary level data was requested for the
report run.
•When true, indicates that detailed data, which includes summary level
data, was requested for the report run.
Date, time when the instance of the report run finished. Only available if the
report instance ran successfully or couldn’t be run because of an error. Date-time
information is in ISO-8601 format.
Date, time stringcompletionDate
Date and time when an instance of the report run was requested. Date-time
information is in ISO-8601 format.
Date, time stringrequestDate
SEE ALSO:
Execute Async
Instance Results
Instance Results
Retrieves results for an instance of a report run asynchronously with or without filters. Depending on your asynchronous report run
request, data can be at the summary level or include details.
Resource URL
/services/data/<latest API version>/analytics/reports/<report ID>/instances/<instance
ID>
155
Instance ResultsReports API Resource Reference
Formats
JSON
HTTP Methods
DescriptionMethod
Retrieves results of an asynchronous report run. See this example.GET
If the given report instance has a status of Success or Error, delete the report instance and return an empty
response body.
DELETE
GET Response Body
DescriptionTypeProperty
BooleanhasDetailRows •When false, report results are at summary level.
•When true, report results are at the record detail level.
When True, all report results are returned.
BooleanallData
When False, detailed data for the first 2000 report rows are returned.
Information about the fields used to build the report.Report metadatareportMetadata
Collection of summary level data or both detailed and summary level data.Fact mapfactMap
Attributes for the instance of the report run.Attributesattributes
Information on report groupings, summary fields, and detailed data columns,
which is available if detailed data is requested.
Report extended
metadata
reportExtendedMetadata
Collection of row groupings.Groupings downgroupingsDown
Collection of column groupings.Groupings acrossgroupingsAcross
Attributes
DescriptionTypeProperty
Unique ID for an instance of a report that was run.Stringid
Stringstatus •New if the report run has just been triggered through a request.
•Success if the report ran.
•Running if the report is being run.
•Error if the report run failed. The instance of a report run can return
an error if, for example, your permission to access the report has been
removed since you requested the run.
156
Instance ResultsReports API Resource Reference
DescriptionTypeProperty
API name of the user that created the instance.StringownerId
Date, time when the instance of the report run finished. Only available if
the report instance ran successfully or couldn’t be run because of an error.
Date-time information is in ISO-8601 format.
Date, time stringcompletionDate
Date and time when an instance of the report run was requested. Date-time
information is in ISO-8601 format.
Date, time stringrequestDate
Format of the resource.Stringtype
Unique report ID.StringreportId
Display name of the report.StringreportName
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
URLTask
/services/data/<latest API version>/analytics/reports
List reports
/services/data/<latest API version>/analytics/reports?cloneId=<report ID>
Copy report
Formats
JSON
HTTP Methods
DescriptionMethod
List of reports that were recently viewed by the API user. See this example.GET
157
Report ListReports API Resource Reference
DescriptionMethod
Create or clone a report.
To create a new report, see this example.
POST
To clone an existing report, see this example.
GET Response Body
DescriptionTypeProperty
Report display name.Stringname
Unique report ID.Stringid
URL that returns report data.Stringurl
URL that retrieves report metadata.StringdescribeUrl
Information for each instance of the report that was run asynchronously.StringinstancesUrl
POST Response Body
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
137[]
crossFilters
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
158
Report ListReports API Resource Reference
DescriptionTypeProperty
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
Report API name.StringdeveloperName
Determines the division of records to include in the report. For example,
West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data and
you have the “Affected by Divisions” permission. If you do not have the
“Affected by Divisions” permission, your reports include records in all
divisions.
ID of the folder that contains the report.StringfolderId
Note: When the report is in the My Personal Custom Reports
folder, folderId = userId. When the report is in the Unfiled Public
Reports folder, folderId = orgId.
Unique identities for each column grouping in a report. The identity is:Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
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
StringreportBooleanFilter
159
Report ListReports API Resource Reference
DescriptionTypeProperty
exceeds 100K AND they are medium or large sized businesses. The
filters are processed by the logic, “(1 OR 2) AND 3.”
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
Defines the scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities you own,
Stringscope
or opportunities your team owns. Valid values depend on the report
type.
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
160
Report ListReports API Resource Reference
DescriptionTypeProperty
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
startDate: Start date.
endDate: End date.
List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the Opportunity
Array of stringsstandardFilters
object are Show, Opportunity Status, and Probability. This list appears
as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering (true)
or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
Query
Returns report data without saving changes to an existing report or creating a new one.
Resource URL
/services/data/<latest API version>/analytics/reports/query
Formats
JSON
HTTP Methods
DescriptionMethod
Run a report without creating or saving the report. Customize your report using reportMetadata that you specify
in the request body. See this example on page 59.
POST
161
QueryReports API Resource Reference
Request Body
Report metadata
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity
is a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
168[]
crossFilters
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
Report API name.StringdeveloperName
Determines the division of records to include in the report. For
example, West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data
and you have the “Affected by Divisions” permission. If you do not
have the “Affected by Divisions” permission, your reports include
records in all divisions.
ID of the folder that contains the report.StringfolderId
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.
162
QueryReports API Resource Reference
DescriptionTypeProperty
Unique identities for each column grouping in a report. The identity
is:
Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
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
StringreportBooleanFilter
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"
}
163
QueryReports API Resource Reference
DescriptionTypeProperty
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
Defines the scope of the data on which you run the report. For
example, you can run the report against all opportunities,
Stringscope
opportunities you own, or opportunities your team owns. Valid values
depend on the report type.
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
startDate: Start date.
endDate: End date.
List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the
Array of stringsstandardFilters
Opportunity object are Show, Opportunity Status, and Probability.
This list appears as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering
(true) or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
164
QueryReports API Resource Reference
DescriptionTypeProperty
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
Chart
DescriptionTypeProperty
Type of chart.StringchartType
Report grouping.Stringgroupings
Indicates whether the report has a legend.BooleanhasLegend
Indicates whether the report shows chart values.BooleanshowChartValues
Unique identities for summary or custom summary formula fields
in the report. For example:
Array of stringssummaries
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom
field column. For custom fields and custom report types, the
identity is a combination of the summary type and the field ID.
Specifies the axis that shows the summary values. Valid values are
X and Y.
StringsummaryAxisLocations
Name of the chart.Stringtitle
Groupings down
DescriptionTypeProperty
API name of the field used as a row grouping.Stringname
Order in which data is sorted within a row grouping. Value can be:StringsortOrder
•Asc for ascending order.
•Desc for descending order.
165
QueryReports API Resource Reference
DescriptionTypeProperty
Interval set on a date field that’s used as a row grouping. Value can
be:
StringdateGranularity
•Day
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
•Calendar Month in Year
•Calendar Day in Month
Summary field that’s used to sort data within a grouping in a report
that’s in summary format. Applies if you have the Aggregate Sort
StringsortAggregate
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
DescriptionTypeProperty
API name of the field used as a column grouping.Stringname
Order in which data is sorted within a column grouping. Value can
be:
StringsortOrder
•Asc for ascending order.
•Desc for descending order.
Interval set on a date field used as a column grouping. Value can
be:
StringdateGranularity
•Day
166
QueryReports API Resource Reference
DescriptionTypeProperty
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
•Calendar Month in Year
•Calendar Day in Month
Filter details
DescriptionTypeProperty
Unique API name for the field that’s being filtered.Stringcolumn
Indicates if this is an editable filter in the user interface.BooleanisRunPageEditable
Unique API name for the condition used to filter a field such as
“greater than” or “not equal to.” Filter conditions depend on the
data type of the field. Valid values are:
Stringoperator
•equals
•notEqual
•lessThan
•greaterThan
•lessOrEqual
•greaterOrEqual
•contains
•notContain
•startsWith
•includes
•excludes
•within (DISTANCE criteria only)
Value by which a field is filtered. For example, the field Age can
be filtered by a numeric value.
For datetime fields, if you make a POST request and specify a
calendar date without including a time, then a default time gets
Stringvalue
included. The time defaults to midnight minus the difference
between your timezone and Greenwich Mean Time (GMT). For
example, if you specify 8/8/2015 and your timezone is Pacific
Standard Time (GMT-700), then the API returns
2015-08-08T07:00:00Z.
167
QueryReports API Resource Reference
Bucket field
DescriptionTypeProperty
The type of bucket. Possible values are number, percent, and
picklist
BucketTypebucketType
API name of the bucket.StringdeveloperName
User-facing name of the bucket.Stringlabel
Specifies whether null values are converted to zero (true) or not
(false).
BooleannullTreatedAsZero
Name of the fields grouped as “Other” (in buckets of BucketType
PICKLIST).
StringotherBucketLabel
Name of the bucketed field.StringsourceColumnName
Describes the values included in the bucket field..Array of
BucketTypeValues
values
Bucket field value
DescriptionTypeProperty
The user-facing name of the bucket.Stringlabel
A list of the values from the source field included in this bucket
category (in buckets of type PICKLIST and buckets of type TEXT).
StringsourceDimensionValues
The greatest range limit under which values are included in this
bucket category (in buckets of type NUMBER).
DoublerangeUpperBound
Cross filter
DescriptionTypeProperty
Information about how to filter the relatedEntity. Use to relate
the primary entity with a subset of the relatedEntity.
Array of Filter details[]criteria
Specifies whether objects returned have a relationship with the
relatedEntity (true) or not (false).
BooleanincludesObject
The name of the object on which the cross filter is evaluated.StringprimaryEntityField
The name of the object that the primaryEntityField is
evaluated against. (The right-hand side of the cross filter).
StringrelatedEntity
The name of the field used to join the primaryEntityField
and relatedEntity.
StringrelatedEntityJoinField
168
QueryReports API Resource Reference
Custom summary formula
DescriptionTypeProperty
The user-facing name of the custom summary formula.Stringlabel
The user-facing description of the custom summary formula.Stringdescription
The format of the numbers in the custom summary formula. Possible
values are number, currency, and percent.
StringformulaType
The number of decimal places to include in numbers.IntegerdecimalPlaces
The name of a row grouping when the downGroupType is
CUSTOM. Null otherwise.
StringdownGroup
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringdownGroupType
The name of a column grouping when the accrossGroupType
is CUSTOM. Null otherwise.
StringacrossGroup
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringacrossGroupType
The operations performed on values in the custom summary formula.Stringformula
Top rows
DescriptionTypeProperty
The number of rows returned in the report.IntegerrowLimit
The sort order of the report rows.Stringdirection
Response Body
DescriptionTypeProperty
Key report attributes and child resource URLs.Attributesattributes
When True, all report results are returned.
BooleanallData
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.
169
QueryReports API Resource Reference
DescriptionTypeProperty
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.
Fact mapfactMap
See these examples of fact map keys.
Collection of column groupings, keys, and their values.Groupings acrossgroupingsAcross
Collection of row groupings, keys, and their values.Groupings downgroupingsDown
When true,the fact map returns values for both summary level
and record level data.
BooleanhasDetailRows
When false, the fact map returns summary values.
Additional information about columns, summaries, and groupings.Report extended
metadata
reportExtendedMetadata
Unique identifiers for groupings and summaries.Report metadatareportMetadata
Attributes
DescriptionTypeProperty
Resource URL to get report metadata.StringdescribeUrl
Resource URL to run a report asynchronously. The report can be
run with or without filters to get summary or both summary and
StringinstancesUrl
detailed data. Results of each instance of the report run are stored
under this URL.
API resource format.Stringtype
Display name of the report.StringreportName
Unique report ID.StringreportId
Fact map
DescriptionTypeProperty
Array of detailed report data listed in the order of the detail
columns provided by the report metadata.
Data cells[]rows
Summary level data including record count for a report.Aggregates[]aggregates
170
QueryReports API Resource Reference
Data cells
DescriptionTypeProperty
The value of a specified cell.Detail column info
data type
value
Display name of the value as it appears for a specified cell in the
report.
Stringlabel
Aggregates
DescriptionTypeProperty
Numeric value of the summary data for a specified cell.Numbervalue
Formatted summary data for a specified cell.Stringlabel
Groupings across
DescriptionTypeProperty
Information for each column grouping as a list.Groupings[]groupings
Groupings
DescriptionTypeProperty
Value of the field used as a row or column grouping. The value
depends on the field’s data type.
Stringvalue
•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
171
QueryReports API Resource Reference
DescriptionTypeProperty
opportunity owner’s Chatter profile page can be a grouping
value.
Unique identity for a row or column grouping. The identity is used
by the fact map to specify data values within each grouping.
Stringkey
Display name of a row or column grouping. For date and time
fields, the label is the localized date or time.
Stringlabel
Second or third level row or column groupings. If there are none,
the value is an empty array.
Arraygroupings
Start date and end date of the interval defined by date
granularity.
Arraydategroupings
Groupings down
DescriptionTypeProperty
Information for each row grouping as a list.Groupings[]groupings
Report Error Codes
Errors can occur at the report level. Report-level error messages are returned in the response header.
When a report-level error occurs, the response header contains an HTTP response code and one of the following error messages:
Error MessageHTTP
Response
Code
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
172
Report Error CodesReports API Resource Reference
Error MessageHTTP
Response
Code
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
Can’t run the report because it doesn’t have any columns selected. Be sure to add fields as columns to the report
through the user interface.
400
The request is invalid because there are no filters. Specify filters or set filters as an empty array to omit them.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.400
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 don’t 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 don’t have permission to run reports. Check that you have the Run Reports user permission.403
You don’t 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.403
Use a valid URL, for example, /services/data/(apiversion)/analytics/reports/(reportID)/describe, to retrieve report
metadata.
404
173
Report Error CodesReports API Resource Reference
Error MessageHTTP
Response
Code
The data you’re trying to access is unavailable.404
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.
415
We ran into an error when fetching this report’s 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.500
The report failed to be saved.500
You’re 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.501
174
Report Error CodesReports API Resource Reference
CHAPTER 6 Report Types API Resource Reference
Use the Report Types API to get information about what report types are available in your org. The Report
Types API is available in API version 39.0 and later.
In this chapter ...
•Report Type List Resources for the Report Types API are available at /services/data/<latest API
version>/analytics/reporttypes. You can query each resource with an HTTP method.
•Report Type
DescriptionSupported
HTTP
Method
Resource
Returns a list of available
report types.
GETReport Type List
/services/data/<latest API
version>/analytics/reportTypes
Returns metadata about
a specified report type.
GETReport Type
/services/data/<latest API
version>/analytics/reportType/<type>
175
Report Type List
Return a list of report types.
Syntax
URI
/vXX.X/analytics/reportTypes
Formats
JSON
HTTP methods
DescriptionMethod
Returns a list of report types.GET
GET Response Body
An array of report type folder objects. Each object contains the following fields:
DescriptionTypeProperty
The end user-facing name of the report type folder.Stringlabel
An array of report types.reportTypes[]reportTypes
reportTypes[]
An array of report type objects. Each object contains the following fields:
DescriptionTypeProperty
A URL link to the report type’s metadata.StringdescribeUrl
The end user-facing name of the report type in the report builder.Stringlabel
The API name of the report type.Stringtype
Report Type
Return metadata about a report type.
Syntax
URI
/vXX.X/analytics/reportTypes/type
176
Report Type ListReport Types API Resource Reference
Formats
JSON
HTTP methods
DescriptionMethod
Return metadata about a report typeGET
GET Request Body
A notification object with desired changes.
DescriptionTypeProperty
Unique identifiers for groupings and summaries.Report metadatareportMetadata
Fields in each section of a report type plus filter information for those
fields.
Report type metadatareportTypeMetadata
Additional information about summaries and groupings.Report extended
metadata
reportExtendedMetadata
Report extended metadata
DescriptionTypeProperty
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.
Aggregate column
information
aggregateColumnInfo
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.
Detail column
information
detailColumnInfo
Map of each row or column grouping to its metadata. Contains values
for each grouping identified in the groupingsDown and
groupingsAcross list.
Grouping column
information
groupingColumnInfo
Aggregate column information
DescriptionTypeProperty
Display name for record count, or the summarized or custom
summary formula field.
Stringlabel
Data type of the summarized or custom summary formula field.StringdataType
Column grouping in the report where the custom summary formula
is displayed. As this example shows in the JSON response and in
StringacrossGroupingContext
the custom summary formula editor of the matrix report, the
177
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
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"
},
}
}
}
Row grouping in the report where the custom summary formula
is displayed. In this example, the custom summary formula for a
StringdownGroupingContext
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"
},
}
}
}
178
Report TypeReport Types API Resource Reference
Detail column information
DescriptionTypeProperty
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.
Stringlabel
The data type of the field that has detailed data. Possible values
are:
StringdataType
•string
•boolean
•double
•int
•percent
•currency
•date
•datetime
•time
•picklist
•multipicklist
•id
•reference
•textarea
•phone
•combobox
•url
•email
•html
Grouping column information
DescriptionTypeProperty
Display name of the field or bucket field used for grouping.Stringlabel
Data type of the field used for grouping. Possible values are:StringdataType
•string
•boolean
•double
•int
•percent
•currency
179
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
•date
•datetime
•time
•picklist
•multipicklist
•id
•reference
•textarea
•phone
•combobox
•url
•email
•html
Level of the grouping. Value can be:
IntegergroupingLevel
•0, 1, or 2. Indicates first, second, or third row level grouping
in summary reports.
•0 or 1. Indicates first or second row or column level grouping
in a matrix report.
Report metadata
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity
is a combination of the summary type and the field ID.
Describes a bucket field.Bucket fieldbuckets
Details about the chart used in a report.Chart[]chart
Cross filters applied to the report.Cross filter on page
187[]
crossFilters
180
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
Describes a custom summary formulas.Custom summary
formula
customSummaryFormula
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.
Stringcurrency
Unique API names for the fields that have detailed data.Array of stringsdetailColumns
Report API name.StringdeveloperName
Determines the division of records to include in the report. For
example, West Coast and East Coast.
Stringdivision
Available only if your organization uses divisions to segment data
and you have the “Affected by Divisions” permission. If you do not
have the “Affected by Divisions” permission, your reports include
records in all divisions.
ID of the folder that contains the report.StringfolderId
Note: When the report is in the My Personal Custom Reports
folder, folderId = userId. When the report is in the Unfiled
Public Reports folder, folderId = orgId.
Unique identities for each column grouping in a report. The identity
is:
Groupings across[]groupingsAcross
•An empty array for reports in summary format as it can’t have
column groupings.
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for a column
grouping.
Unique identities for each row grouping in a report. The identity is:Groupings down[]groupingsDown
•BucketField_(ID) for bucket fields.
•ID of a custom field when the custom field is used for grouping.
Indicates whether to include detailed data with the summary data.BooleanhasDetailRows
Indicates whether the report shows the record count.BooleanhasRecordCount
List of historical snapshot dates.Array of stringshistoricalSnapshotDates
Unique report ID.Stringid
Display name of the report.Stringname
181
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
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
StringreportBooleanFilter
revenue exceeds 100K AND they are medium or large sized
businesses. The filters are processed by the logic, “(1 OR 2) AND 3.”
{
...
"reportBooleanFilter": "(1 OR 2) AND
3",
"reportFilters": [
{
"value":
"Analyst,Integrator,Press,Other",
"column": "TYPE",
"operator": "notEqual"
},
{
"value": "100,000",
"column": "SALES",
"operator": "greaterThan"
},
{
"value": "Small",
"column": "Size",
"operator": "notEqual"
}
]
}
}
List of each custom filter in the report along with the field name, filter
operator, and filter value.
Filter details[]reportFilters
Format of the report. Value can be:StringreportFormat
•TABULAR
•SUMMARY
•MATRIX
Unique API name and display name for the report type.
type: Of type string, this is the unique identifier of the report type.
Report typereportType
label: Of type string, this is the display name of the report type.
Defines the scope of the data on which you run the report. For
example, you can run the report against all opportunities,
Stringscope
opportunities you own, or opportunities your team owns. Valid values
depend on the report type.
182
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
Indicates whether the report shows the grand total.BooleanshowGrandTotal
Indicates whether the report shows subtotals, such as column or row
totals.
BooleanshowSubtotals
API name of the field on which the report is sorted and the direction
of the sort (asc or desc).
Array of stringssortBy
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.
Array of stringsstandardDateFilter
durationValue: The range for which you want to run the report.
The value is a date literal or 'CUSTOM.'
startDate: Start date.
endDate: End date.
List of filters that show up in the report by default. The filters vary by
report type. For example, standard filters for reports on the
Array of stringsstandardFilters
Opportunity object are Show, Opportunity Status, and Probability.
This list appears as name-value string pairs.
Indicates whether the report type supports role hierarchy filtering
(true) or not (false).
BooleansupportsRoleHierarchy
Describes a row limit filter applied to the report.Top rowstopRows
Unique user or role ID of the user or role used by the report's role
hierarchy filter.
If specified, a role hierarchy filter is applied to the report. If unspecified,
no role hierarchy filter is applied to the report.
StringuserOrHierarchyFilterId
Chart
DescriptionTypeProperty
Type of chart.StringchartType
Report grouping.Stringgroupings
Indicates whether the report has a legend.BooleanhasLegend
Indicates whether the report shows chart values.BooleanshowChartValues
Unique identities for summary or custom summary formula fields
in the report. For example:
Array of stringssummaries
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
183
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom
field column. For custom fields and custom report types, the
identity is a combination of the summary type and the field ID.
Specifies the axis that shows the summary values. Valid values are
X and Y.
StringsummaryAxisLocations
Name of the chart.Stringtitle
Groupings down
DescriptionTypeProperty
API name of the field used as a row grouping.Stringname
Order in which data is sorted within a row grouping. Value can be:StringsortOrder
•Asc for ascending order.
•Desc for descending order.
Interval set on a date field that’s used as a row grouping. Value can
be:
StringdateGranularity
•Day
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
•Calendar Month in Year
•Calendar Day in Month
Summary field that’s used to sort data within a grouping in a report
that’s in summary format. Applies if you have the Aggregate Sort
StringsortAggregate
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": [
184
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
{
"name": "USERS.NAME",
"sortOrder": "Desc",
"dateGranularity": "None",
"sortAggregate": "s!SALES"
}
]
}
Groupings across
DescriptionTypeProperty
API name of the field used as a column grouping.Stringname
Order in which data is sorted within a column grouping. Value can
be:
StringsortOrder
•Asc for ascending order.
•Desc for descending order.
Interval set on a date field used as a column grouping. Value can
be:
StringdateGranularity
•Day
•Calendar Week
•Calendar Month
•Calendar Quarter
•Calendar Year
•Fiscal Quarter
•Fiscal Year
•Calendar Month in Year
•Calendar Day in Month
Filter details
DescriptionTypeProperty
Unique API name for the field that’s being filtered.Stringcolumn
Indicates if this is an editable filter in the user interface.BooleanisRunPageEditable
Unique API name for the condition used to filter a field such as
“greater than” or “not equal to.” Filter conditions depend on the
data type of the field. Valid values are:
Stringoperator
•equals
185
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
•notEqual
•lessThan
•greaterThan
•lessOrEqual
•greaterOrEqual
•contains
•notContain
•startsWith
•includes
•excludes
•within (DISTANCE criteria only)
Value by which a field is filtered. For example, the field Age can
be filtered by a numeric value.
For datetime fields, if you make a POST request and specify a
calendar date without including a time, then a default time gets
Stringvalue
included. The time defaults to midnight minus the difference
between your timezone and Greenwich Mean Time (GMT). For
example, if you specify 8/8/2015 and your timezone is Pacific
Standard Time (GMT-700), then the API returns
2015-08-08T07:00:00Z.
Bucket field
DescriptionTypeProperty
The type of bucket. Possible values are number, percent, and
picklist
BucketTypebucketType
API name of the bucket.StringdeveloperName
User-facing name of the bucket.Stringlabel
Specifies whether null values are converted to zero (true) or not
(false).
BooleannullTreatedAsZero
Name of the fields grouped as “Other” (in buckets of BucketType
PICKLIST).
StringotherBucketLabel
Name of the bucketed field.StringsourceColumnName
Describes the values included in the bucket field..Array of
BucketTypeValues
values
186
Report TypeReport Types API Resource Reference
Bucket field value
DescriptionTypeProperty
The user-facing name of the bucket.Stringlabel
A list of the values from the source field included in this bucket
category (in buckets of type PICKLIST and buckets of type TEXT).
StringsourceDimensionValues
The greatest range limit under which values are included in this
bucket category (in buckets of type NUMBER).
DoublerangeUpperBound
Cross filter
DescriptionTypeProperty
Information about how to filter the relatedEntity. Use to relate
the primary entity with a subset of the relatedEntity.
Array of Filter details[]criteria
Specifies whether objects returned have a relationship with the
relatedEntity (true) or not (false).
BooleanincludesObject
The name of the object on which the cross filter is evaluated.StringprimaryEntityField
The name of the object that the primaryEntityField is
evaluated against. (The right-hand side of the cross filter).
StringrelatedEntity
The name of the field used to join the primaryEntityField
and relatedEntity.
StringrelatedEntityJoinField
Custom summary formula
DescriptionTypeProperty
The user-facing name of the custom summary formula.Stringlabel
The user-facing description of the custom summary formula.Stringdescription
The format of the numbers in the custom summary formula. Possible
values are number, currency, and percent.
StringformulaType
The number of decimal places to include in numbers.IntegerdecimalPlaces
The name of a row grouping when the downGroupType is
CUSTOM. Null otherwise.
StringdownGroup
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringdownGroupType
The name of a column grouping when the accrossGroupType
is CUSTOM. Null otherwise.
StringacrossGroup
187
Report TypeReport Types API Resource Reference
DescriptionTypeProperty
Where to display the aggregate of the custom summary formula.
Possible values are all, custom, and grand_total.
StringacrossGroupType
The operations performed on values in the custom summary formula.Stringformula
Top rows
DescriptionTypeProperty
The number of rows returned in the report.IntegerrowLimit
The sort order of the report rows.Stringdirection
Report type metadata
DescriptionTypeProperty
All fields in the report type organized by section.Categories[]categories
Lists all the possible field data types that can be used to filter
the report. Each data type, such as phone, percent, currency,
or picklist has two properties:
name: Of type string, this is a unique API name for each field
type’s filter criteria. Use this API name in the metadata to
define filter criteria for a report.
Filter operator
reference
dataTypeFilterOperatorMap
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.
Default division and list of all possible record-level divisions
that can be used in a report.
Division info[]divisionInfo
Scope of the data on which you run the report. For example,
you can run the report against all opportunities, opportunities
Scope info[]scopeInfo
you own, or opportunities your team owns. Valid values
depend on the report type.
List of standard date filters available in reports.Standard date filter
duration groups[]
standardDateFilterDurationGroups
List of filters that show up in the report by default. The filters
vary by report type. For example, standard filters for reports
Array of stringsstandardFilterInfos
on the Opportunity object are Show, Opportunity Status, and
Probability. This list appears as name-value string pairs.
188
Report TypeReport Types API Resource Reference
Categories
DescriptionTypeProperty
Display name of a section in the report type under which fields are
organized. For example, in an Accounts with Contacts custom report
Stringlabel
type, Account General is the display name of the section that
has fields on general account information.
Information for all fields in the report type organized under a
particular section’s unique API name.
Column mapcolumns
Division info
DescriptionTypeProperty
Users are assigned a default division that applies to their newly
created accounts, leads, and custom objects that are enabled for
divisions.
StringdefaultValue
All division values. Division values have two properties:
label: Display name of a division.
Stringvalues
name: Unique API name of a division.
Column map
DescriptionTypeProperty
Display name of a field.Stringlabel
All filter values for a field, if the field data type is of picklist,
multi-select picklist, boolean, or checkbox. For example, checkbox
String arrayfilterValues
fields always have a value of True or False. For fields of other
data types, the filter value is an empty array because their values
can’t be determined. Filter values have two properties:
name: Unique API name for a filter value. Of type string.
label: Display name of a filter value. Of type string.
Data type of the field.StringdataType
False means that the field is of a type that can’t be filtered. For
example, fields of the type Encrypted Text can’t be filtered.
Booleanfilterable
189
Report TypeReport Types API Resource Reference
Scope Info
DescriptionTypeProperty
Default scope of the data on which you run the report.StringdefaultValue
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.
Array of stringsvalues
label: Display name of the scope.
value: Value of the scope.
Standard date filter duration groups
DescriptionTypeProperty
Display name of the standard date filter grouping. Valid values
are Calendar Year, Calendar Quarter, Calendar Month, Calendar
Stringlabel
Week, Fiscal Year, Fiscal Quarter, Day and custom value based
on a user-defined date range.
Details about each possible relative date filter defined under
the standard date filter grouping.
Standard date filter
durations[]
standardDateFilterDurations
Standard date filter durations
DescriptionTypeProperty
End date of a date filter.StringendDate
Display name of a date filter. Valid date filters are relative date
filters—like Current FY and Current FQ—and custom
date filters.
Stringlabel
Start date of a date filter.StringstartDate
API name of a date filter. Valid date filters are relative date
filters—like THIS_FISCAL_YEAR and
NEXT_FISCAL_QUARTER—and custom date filters.
Stringvalue
190
Report TypeReport Types API Resource Reference
CHAPTER 7 Dashboards API Resource Reference
The Dashboards API provides several resources for accessing and refreshing dashboards.
In this chapter ...
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.
•Dashboard List
•Dashboard Results
•Dashboard Describe
DescriptionSupported
HTTP
Method
Resource
•Dashboard Status
•Dashboard and
Component Error
Codes
Returns a list of recently used dashboards.GET
Dashboard List
Makes a copy of a dashboard.POST
Returns the metadata, data, and status for the specified dashboard.GET
Dashboard Results
Returns details about specified dashboard components.POST
Triggers a dashboard refresh.PUT
Saves a dashboard.PATCH
Deletes a dashboard.DELETE
Returns the status for the specified dashboard.GETDashboard Status
Returns metadata for the specified dashboard, including dashboard
components, filters, layout, and the running user.
GETDashboard
Describe
191
Dashboard List
Returns a list of recently used dashboards or clones a dashboard.
Syntax
URI
/vXX.X/analytics/dashboards
Formats
JSON
HTTP methods
DescriptionMethod
Returns a list of dashboards that were recently viewed by the API user. See this example.GET
Makes a copy of a dashboard. See this example.POST
Authentication
Authorization: Bearer token
GET Response body
An array of recent dashboard objects. Each object contains the following fields:
DescriptionTypeProperty
Unique identifier of the dashboard.Stringid
Localized display name of the dashboard.Stringname
Dashboard status URL.StringstatusUrl
Dashboard result URL.Stringurl
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
192
Dashboard ListDashboards API Resource Reference
Or, with optional parameters:
/vXX.X/analytics/dashboards/dashboardID
?runningUser=runningUserID&filter1=filter1ID&filter2=filter2ID&filter3=filter3ID
Formats
JSON
HTTP methods
DescriptionMethod
Returns metadata, data, and status for the specified dashboard. See this example.GET
Returns details about one or more dashboard components from a specified dashboard. See this example.POST
Triggers a dashboard refresh. See this example.PUT
Saves a dashboard. See this example.PATCH
Deletes a dashboard. See this example.DELETE
Authentication
Authorization: Bearer token
Parameters
The following optional parameters can be used with the GET and PUT methods:
DescriptionParameter Name
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.
runningUser
Identifier of the selected filter option for the first filter. Gives an error if the filter option is
invalid.
filter1
Identifier of the selected filter option for the second filter. Gives an error if the filter option is
invalid.
filter2
Identifier of the selected filter option for the third filter. Gives an error if the filter option is
invalid.
filter3
GET, POST, and PUT Response body
DescriptionTypeProperty
Ordered array containing data and status for each component of the dashboard.Component data[]componentData
Metadata for the entire dashboard.Dashboard metadatadashboardMetadata
193
Dashboard ResultsDashboards API Resource Reference
Attributes
DescriptionTypeProperty
Unique identifier of dashboard.StringdashboardId
Dashboard name.StringdashboardName
The URL of the status resource for the dashboard.UrlstatusUrl
This property is always set to Dashboard.Stringtype
Component data
DescriptionTypeProperty
Unique identifier of the component.StringcomponentId
Report metadata and summary data for the dashboard component. Uses
the same data format as the Report API.
Report resultsreportResult
Queue and data status of the component.Component statusstatus
Component status
DescriptionTypeProperty
Status of the data set of the component. Value can be:StringdataStatus
•NODATA: The data set was never generated or is invalid due to a
change in the report.
•DATA: The data set is available and was last refreshed at the
refreshDate.
•ERROR: A component error has occurred. Details can be found in
errorCode, errorMessage, and errorSeverity.
Unique identifier of error message. This property is only populated in case
of error.
StringerrorCode
Localized error message. This property is only populated in case of error.StringerrorMessage
Severity of error code and message. Value can be:StringerrorSeverity
•Error
•Warning
This property is only populated in case of error.
Date and time of last refresh in ISO-8601 format.Date and time stringrefreshDate
Refresh status of the component. Value can be:StringrefreshStatus
•IDLE: The component is not currently being refreshed.
•RUNNING: The component is currently being refreshed.
194
Dashboard ResultsDashboards API Resource Reference
Dashboard metadata
DescriptionTypeProperty
Attributes for the dashboard resource, such as name, identifier, and
references to other related resources.
Attributesattributes
Indicates whether the user is allowed to select a specific running user.
Always true for team dashboards.
BooleancanChangeRunningUser
Indicates whether dashboard filters persist after closing the dashboard
(true) or not (false). Filters that persist keep the dashboard filtered
BooleancanUseStickyFilter
the next time you open it. Filters persist for users on a per-user basis, so if
you apply a filter then it doesn’t persist for other people.
Ordered array of components in this dashboard.Components[]components
Dashboard description.Stringdescription
Indicates whether a dashboard is a dynamic dashboard, a dashboard with
running users, or a standard dashboard. Possible values are:
StringdashboardType
•SpecifiedUser — Dashboard readers view data as though they
are the person specified by runningUser
•LoggedInUser — Dashboard readers view data as themselves.
The dashboard is a dynamic dashboard.
•MyTeamUser — Dashboard readers view data as the person
specified by runningUser by default. If they have the “View All
Data” user permission then they can change the runningUser to
anyone. If they have the “View My Team’s Dashboards” user permission
then they can change the runningUser to people subordinate
to them in the role hierarchy.
Unique API name of the dashboard.StringdeveloperName
Ordered array of filters for this dashboard. The dashboard can have 0-3
filters.
Filters[]filters
ID of the folder that contains the dashboard.StringfolderId
Unique identifier of dashboard.Stringid
Component layout for this dashboard.Layoutlayout
Dashboard name.Stringname
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.
Running userrunningUser
195
Dashboard ResultsDashboards API Resource Reference
Components
DescriptionTypeProperty
Index into the component data array in the response body.IntegercomponentData
Footer of the component.Stringfooter
Header of the component.Stringheader
Unique identifier of the component.Stringid
Component properties, including type-specific visualization properties.
Properties (for Report
component type)
properties
Properties (for
Visualforce page
component type)
Unique identifier of the underlying report.StringreportId
Title of the componentStringtitle
Type of the component. Value can be:Stringtype
•Report
•VisualforcePage
If the component is an SControl, the value is not set.
Filters
DescriptionTypeProperty
If there is no error with a dashboard filter, then null. Otherwise, the error
message is returned.
StringerrorMessage
Localized display name of filter.Stringname
Ordered array of possible filter options.Filter optionoptions
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.
IntegerselectedOption
Filter option
DescriptionTypeProperty
Optional alias of the filter option.Stringalias
Unique identifier of the filter option. Used as a value for the filter1,
filter2, and filter3 parameters.
Stringid
196
Dashboard ResultsDashboards API Resource Reference
DescriptionTypeProperty
Unique API name for the filter operation. Valid filter operations depend
on the data type of the filter field. Value can be:
Stringoperation
•equals
•notEqual
•lessThan
•greaterThan
•lessOrEqual
•greaterOrEqual
•contains
•notContain
•startsWith
•includes
•excludes
•within
•between
Value to filter on. Used for all operations except between.Stringvalue
Start value when using a between operation. Not set for all other
operations.
StringstartValue
End value when using a between operation. Not set for all other
operations.
StringendValue
Layout
DescriptionTypeProperty
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.
Columns[]columns
Layout for dashboards. This property is available only if the dashboard was
created using Lightning Experience.
Componentscomponents
Columns
DescriptionTypeProperty
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.
Integer[]components
197
Dashboard ResultsDashboards API Resource Reference
Components
DescriptionTypeProperty
Width of component in columns. For example, if colspan=3, then
the component spans 3 columns.
Integercolspan
Height of component in rows. For example, if rowspan=4, then the
component spans 4 rows.
Integerrowspan
Column position on the grid.Stringcolumn
Row position on the grid.Stringrow
Running user
DescriptionTypeProperty
Display name of running user.StringdisplayName
Unique identifier of running user.Stringid
picklistColors
DescriptionTypeProperty
The color in hexadecimal format used to represent a picklist value.Stringcolor
Properties (for Report component type)
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in the
report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount column.
•x!Amount represents the maximum value of the Amount column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is a
combination of the summary type and the field ID.
Indicates whether groupings and aggregates are automatically selected.
Valid values are true and false.
BooleanautoSelectColumns
Report groupings included in the dashboard.Stringgroupings
Maximum number of rows to be rendered, based on the sort value.NumbermaxRows
198
Dashboard ResultsDashboards API Resource Reference
DescriptionTypeProperty
Sorting information for the component.Sortsort
Indicates whether the dashboard component uses the chart as defined
in the report. Valid values are true and false.
BooleanuseReportChart
Type-specific visualization properties.
Visualization properties
(Chart)
visualizationProperties
Visualization properties
(Table)
Visualization properties
(Metric)
Visualization properties
(Gauge)
Type of the component. Value can be:StringvisualizationType
•Bar
•Column
•Donut
•Funnel
•Gauge
•Line
•Metric
•Pie
•Scatter
•Table
Sort
DescriptionTypeProperty
Developer name for a sorted column.Stringcolumn
Sort order. Value can be:StringsortOrder
•asc
•desc
Visualization properties (Chart)
DescriptionTypeProperty
Range of values specified for the axis.StringaxisRange
Type of second-level grouping.StringgroupByType
199
Dashboard ResultsDashboards API Resource Reference
DescriptionTypeProperty
Position of legend on the grid. Valid values are bottom, right, and
none.
StringlegendPosition
Indicates whether to include values in the chart. Valid values are true
and false.
BooleanshowValues
Visualization properties (Table)
DescriptionTypeProperty
Break points for the table component.Break point[]breakPoints
Columns of the table component.Table column[]tableColumns
Visualization properties (Metric)
DescriptionTypeProperty
Break points for the metric component.Break point[]breakPoints
Label for the metric component.StringmetricLabel
Visualization properties (Gauge)
DescriptionTypeProperty
Break points for the gauge component.Break point[]breakPoints
Break point
DescriptionTypeProperty
Aggregate column developer name that the break points have been
applied to.
StringaggregateName
Break values for a break point.Break[]breaks
Break
DescriptionTypeProperty
A hex value representing the color for the break point.Stringcolor
Note: A color value of black displays only 1 character (0)
instead of 6 characters (000000).
200
Dashboard ResultsDashboards API Resource Reference
DescriptionTypeProperty
Lower bound for the break point.NumberlowerBound
Upper bound for the break point.NumberupperBound
Table column
DescriptionTypeProperty
Developer name for the aggregate or grouping column.Stringcolumn
Indicates whether the column value is shown as a percent.BooleanisPercent
The number of decimal places for the column value.Numberscale
Indicates whether the column shows the total.BooleanshowTotal
Type of the column. Value can be:Stringtype
•aggregate
•grouping
Properties (for Visualforce page component type)
DescriptionTypeProperty
Developer name of the Visualforce page.StringpageName
Height of the Visualforce page, in pixels.Stringheight
tableChatterPhotoUrls
DescriptionTypeProperty
URL pointing to a user's Chatter photo.StringchatterPhotoUrl
PUT Response body
DescriptionTypeProperty
URL of the status resource for the dashboard.StringstatusUrl
POST Request body
DescriptionTypeProperty
Dashboard component ids.Array of StringscomponentIds
201
Dashboard ResultsDashboards API Resource Reference
Dashboard Describe
Returns metadata for the specified dashboard, including dashboard components, filters, layout, and the running user.
Syntax
URI
/vXX.X/analytics/dashboards/dashboardID/describe
Formats
JSON
HTTP methods
GET
Parameters
DescriptionParameter
Optional. Specifies whether or not to return properties for each dashboard component. The default value is true.
Valid values are:
loadComponentData
•true — Return component properties.
•false — Don’t return component properties. The properties value instead returns null.
Authentication
Authorization: Bearer token
Example
See this example, Get Dashboard Metadata.
Response body
DescriptionTypeProperty
Ordered array of components in this dashboard.Component[]components
Ordered array of filters for this dashboard. The dashboard can have 0 to 3 filters.Filter[]filters
Component layout for this dashboardLayoutlayout
The running user, which is either specified at dashboard design time or is
overriden by the runningUser parameter. For dynamic dashboards, this
is always the current user.
Running userrunningUser
202
Dashboard DescribeDashboards API Resource Reference
Components
DescriptionTypeProperty
Index into the component data array in the response body.IntegercomponentData
Footer of the component.Stringfooter
Header of the component.Stringheader
Unique identifier of the component.Stringid
Component properties, including type-specific visualization properties.
Properties (for Report
component type)
properties
Properties (for Visualforce
page component type)
Unique identifier of the underlying report.StringreportId
Title of the componentStringtitle
Type of the component. Value can be:Stringtype
•Report
•VisualforcePage
If the component is an SControl, the value is not set.
Properties (for Report component type)
DescriptionTypeProperty
Unique identities for summary or custom summary formula fields in
the report. For example:
Array of stringsaggregates
•a!Amount represents the average for the Amount column.
•s!Amount represents the sum of the Amount column.
•m!Amount represents the minimum value of the Amount
column.
•x!Amount represents the maximum value of the Amount
column.
•s!<customfieldID> represents the sum of a custom field
column. For custom fields and custom report types, the identity is
a combination of the summary type and the field ID.
Indicates whether groupings and aggregates are automatically selected.
Valid values are true and false.
BooleanautoSelectColumns
Report groupings included in the dashboard.Stringgroupings
Maximum number of rows to be rendered, based on the sort value.NumbermaxRows
203
Dashboard DescribeDashboards API Resource Reference
DescriptionTypeProperty
Sorting information for the component.Sortsort
Indicates whether the dashboard component uses the chart as defined
in the report. Valid values are true and false.
BooleanuseReportChart
Type-specific visualization properties.
Visualization properties
(Chart)
visualizationProperties
Visualization properties
(Table)
Visualization properties
(Metric)
Visualization properties
(Gauge)
Type of the component. Value can be:StringvisualizationType
•Bar
•Column
•Donut
•Funnel
•Gauge
•Line
•Metric
•Pie
•Scatter
•Table
Sort
DescriptionTypeProperty
Developer name for a sorted column.Stringcolumn
Sort order. Value can be:StringsortOrder
•asc
•desc
Visualization properties (Chart)
DescriptionTypeProperty
Range of values specified for the axis.StringaxisRange
Type of second-level grouping.StringgroupByType
204
Dashboard DescribeDashboards API Resource Reference
DescriptionTypeProperty
Position of legend on the grid. Valid values are bottom, right, and
none.
StringlegendPosition
Indicates whether to include values in the chart. Valid values are true
and false.
BooleanshowValues
Visualization properties (Table)
DescriptionTypeProperty
Break points for the table component.Break point[]breakPoints
Columns of the table component.Table column[]tableColumns
Visualization properties (Metric)
DescriptionTypeProperty
Break points for the metric component.Break point[]breakPoints
Label for the metric component.StringmetricLabel
Visualization properties (Gauge)
DescriptionTypeProperty
Break points for the gauge component.Break point[]breakPoints
Properties (for Visualforce page component type)
DescriptionTypeProperty
Developer name of the Visualforce page.StringpageName
Height of the Visualforce page, in pixels.Stringheight
Filters
DescriptionTypeProperty
If there is no error with a dashboard filter, then null. Otherwise, the error
message is returned.
StringerrorMessage
Localized display name of filter.Stringname
Ordered array of possible filter options.Filter optionoptions
205
Dashboard DescribeDashboards API Resource Reference
DescriptionTypeProperty
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.
IntegerselectedOption
Filter option
DescriptionTypeProperty
Optional alias of the filter option.Stringalias
Unique identifier of the filter option. Used as a value for the filter1,
filter2, and filter3 parameters.
Stringid
Unique API name for the filter operation. Valid filter operations depend
on the data type of the filter field. Value can be:
Stringoperation
•equals
•notEqual
•lessThan
•greaterThan
•lessOrEqual
•greaterOrEqual
•contains
•notContain
•startsWith
•includes
•excludes
•within
•between
Value to filter on. Used for all operations except between.Stringvalue
Start value when using a between operation. Not set for all other
operations.
StringstartValue
End value when using a between operation. Not set for all other
operations.
StringendValue
206
Dashboard DescribeDashboards API Resource Reference
Layout
DescriptionTypeProperty
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.
Columns[]columns
Layout for dashboards. This property is available only if the dashboard was
created using Lightning Experience.
Componentscomponents
Columns
DescriptionTypeProperty
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.
Integer[]components
Components
DescriptionTypeProperty
Width of component in columns. For example, if colspan=3, then the
component spans 3 columns.
Integercolspan
Height of component in rows. For example, if rowspan=4, then the
component spans 4 rows.
Integerrowspan
Column position on the grid.Stringcolumn
Row position on the grid.Stringrow
Running user
DescriptionTypeProperty
Display name of running user.StringdisplayName
Unique identifier of running user.Stringid
Dashboard Status
Returns the status for the specified dashboard.
207
Dashboard StatusDashboards API Resource Reference
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:
DescriptionParameter Name
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.
runningUser
ID of the selected filter option for the first filter. Gives an error if the filter option is invalid.filter1
ID of the selected filter option for the second filter. Gives an error if the filter option is invalid.filter2
ID of the selected filter option for the third filter. Gives an error if the filter option is invalid.filter3
Response body
DescriptionTypeProperty
Status for each component of the dashboard. The order of the array is the same
as in previous calls, unless the dashboard has changed in the meantime.
Component status with
id[]
componentStatus
Component status with id
DescriptionTypeProperty
Unique ID of the dashboard component.StringcomponentId
Date and time of last refresh in ISO-8601 format.Date and time stringrefreshDate
Refresh status of the component. Value can be:StringrefreshStatus
•IDLE: The component is not currently being refreshed.
•RUNNING: The component is currently being refreshed.
208
Dashboard StatusDashboards API Resource Reference
Dashboard and Component Error Codes
Errors can occur at the dashboard level and at the component level.
Dashboard-level error messages are returned in the response header, and component-level error messages are returned as part of the
component status object.
Dashboard-level errors
When a dashboard-level error occurs, the response header contains an HTTP response code and one of the following error messages:
Error MessageHTTP
Response
Code
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.400
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.
errorSeverityerrorMessageerrorCode
ErrorThis component must have a type and a data source.201
ErrorThe source report isn't available; it's been deleted or isn't in a folder accessible to the dashboard's
running user.
202
ErrorThis report can no longer be edited or run. Your administrator has disabled all reports for the
custom or external object, or its relationships have changed.
203
ErrorThe source report is based on a report type that is inaccessible to the dashboard's running user.205
ErrorUnable to run source report because its definition is invalid.208
209
Dashboard and Component Error CodesDashboards API Resource Reference
errorSeverityerrorMessageerrorCode
ErrorThis report cannot be used as the source for this component. If it is a summary or matrix report,
add one or more groupings in the report. If it is a tabular report with a row limit, specify the
Dashboard Settings in the report.
209
ErrorThis row-limited tabular report cannot be used as the source for this component. Use the
dashboard component editor to specify the data you want to display, or specify the Dashboard
Settings in the report.
210
ErrorTo use this row-limited tabular report as the source, edit the report and specify the Name and
Value under Dashboard Settings. When updating the report, make sure you are the running user
of the dashboard.
211
ErrorGroupings and combination charts are not available for a row-limited tabular report. Set “Group
By” to None and deselect “Plot Additional Values.”
212
ErrorThe results below may be incomplete because the underlying report produced too many summary
rows, and the sort order of the component is different from the sort order in the underlying
report. Try adding filters to the report to reduce the number of rows returned.
300
WarningResults may be incomplete because the source report had too many summary rows. Try filtering
the report to reduce the number of rows returned.
301
WarningThe component can't be displayed because the source report exceeded the time limit.302
ErrorThe component can't be displayed because the source report failed to run.303
ErrorThe 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.
304
ErrorThe component can't be displayed because the field(s) you chose for the filter are unavailable.305
ErrorYou can’t filter this component because data is in the joined report format. To filter the component,
change its report format.
308
ErrorThe underlying report uses a snapshot date that is out of range.309
210
Dashboard and Component Error CodesDashboards API Resource Reference
CHAPTER 8 Analytics Notifications API Resource Reference
Use the Analytics Notifications API to work set up custom analytics notifications. The Analytics Notifications
API is available in API version 38.0 and later.
In this chapter ...
•Analytics Notification
List Resources for the Analytics Notifications API are available at /services/data/<latest API
version>/analytics/notifications. You can query each resource with an HTTP method.
•Analytics Notification
DescriptionSupported
HTTP
Method
Resource
•Analytics Notification
Limits
Returns a list of recent notifications.GET
Analytics
Notification List
/services/data/<latest
API
version>/analytics/notifications
Create an analytics notification.
POST
Save changes to the notification as specified in the request body.PUT
Analytics
Notification
/services/data/<latest
API
version>/analytics/notifications/<Id>
Delete the notification. Deleted notifications can't be recovered.DELETE
Check to see how many more analytics notifications you can create.GETAnalytics
Notification Limits
/services/data/<latest
API
version>/analytics/notifications/limits
211
Analytics Notification List
Return a list of analytics notifications (GET) or create an analytics notification (POST).
Syntax
URI
/vXX.X/analytics/notifications?source=waveNotification
Formats
JSON
HTTP methods
DescriptionMethod
Returns a list of analytics notifications.GET
Create an analytics notification.POST
Parameters
DescriptionParameter
Required for GET calls. Specifies what type of analytics notification to return. Valid values are:source
•lightningSubscribe — report subscriptions
•waveNotification — Wave notifications
Optional. Return notifications for a single record. Valid values are:recordId
•reportId— Unique report ID
•lensId— Unique Wave lens ID
GET and POST Response Body
An array of notification objects. Each object contains the following fields:
DescriptionTypeProperty
Indicates whether the notification is being sent (true) or not (false).Booleanactive
Describes details of a Wave notification. Only applicable when source is
waveNotification.
WaveConfiguration[]configuration
Date and time when the notification was created (in ISO 8601 format).DateTimecreatedDate
Indicates whether the notification is deactivated after it's sent (true) or not
(false). Deactivation doesn't delete the notification.
The default value is false.
BooleandeactivateOnTrigger
212
Analytics Notification ListAnalytics Notifications API Resource Reference
DescriptionTypeProperty
Unique notification ID.Stringid
Date and time when the notification was last modified (in ISO 8601 format).DateTimelastModifiedDate
Display name of the notification.Stringname
Unique ID of the record that the notification describes. Valid values are:StringrecordId
•reportId
•lensId
Details about the notification's schedule.Schedule[]schedule
Indicates the type of notification. Possible values are:Stringsource
•lightningSubscribe — report subscriptions
•waveNotification — Wave notifications
Specifies what happens when the notification runs. For example, sending an
email with report results.
Threshold[]thresholds
Schedule
DescriptionTypeProperty
How frequently the notification is invoked. Possible values are:Stringfrequency
•daily — Every day
•weekly — One or more days each week
•monthly — One or more days each month
Only necessary when frequency is monthly. Possible values are:StringfrequencyType
•relative — Days which can change month-to-month, as described
by details.
•specific — Fixed monthly dates, as described by details.
Describes the notification schedule. Varies depending on whether
frequency is daily, weekly, or monthly.
ScheduleDetail[]details
ScheduleDetail (frequency is daily)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
213
Analytics Notification ListAnalytics Notifications API Resource Reference
ScheduleDetail (frequency is weekly)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
The days of the week on which the notification is invoked. Possible values
are:
String[]daysOfWeek
•mon — Monday
•tue — Tuesday
•wed — Wednesday
•thu — Thursday
•fri — Friday
•sat — Saturday
•sun — Sunday
ScheduleDetail (frequency is monthly, frequencyType is relative)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
The week in the month during which the notification is invoked. Possible
values are:
StringweekInMonth
•first — First week
•second — Second week
•third — Third week
•fourth — Fourth week
The day of the week on which the notification is invoked. Possible values
are:
StringdayInWeek
•mon — Monday
•tue — Tuesday
•wed — Wednesday
•thu — Thursday
•fri — Friday
•sat — Saturday
•sun — Sunday
•weekday — Weekday
•weekend — Weekend day
214
Analytics Notification ListAnalytics Notifications API Resource Reference
ScheduleDetail (frequency is monthly, frequencyType is specific)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
The days of the month on which the notification is invoked. Possible values
are integers from 1 to 31, and -1 (which represents the last day of the
month).
Integer[]daysOfMonth
Threshold
DescriptionTypeProperty
Specifies when the notification is invoked (other than date and time criteria).
Possible values are:
Stringtype
•always — Always invoke the notification
•onError — Invoke the notification when there is an error
•condition — Invoke the notification based on criteria described by
conditions
Describes conditions that govern when the notification is invoked.Condition[]conditions
Specifies what action is taken when the notification is invoked.Action[]actions
Condition
DescriptionTypeProperty
The data field which is operated on.StringcolName
The comparison value which is used by the operation.Stringvalue
The operation which is used to evaluate the condition. Possible values are:Stringoperation
•equal — colName and value are equal
•notEqual — colName and value are not equal
•greaterThan — colName is greater than value
•lessThan — colName is less than value
•greaterThanEqual — colName is greater than or equal to
value
•lessThanEqual — colName is less than or equal to value
215
Analytics Notification ListAnalytics Notifications API Resource Reference
Action
DescriptionTypeProperty
The type of action to perform when the notification is invoked. Possible
values are:
Stringtype
•sendEmail — Send an email to recipients
A basic configuration used for passing arguments to Apex pages.StringapexConfiguration
Returns null. Reserved for future use.Configconfiguration
WaveConfiguration
DescriptionTypeProperty
Optional. The Id of the Wave dashboard widget to which the notification is
anchored.
Stringanchor
Optional. Description of selected filters at the time of notification creation.Stringfilter
Required. SAQL query which is run when the notification is invoked.Stringquery
Required. Collection of Wave datasets referenced by the notification.WaveDataset[]datasets
WaveDataset
DescriptionTypeProperty
Required. Id of the Wave dataset.Stringid
Optional. Developer name of the Wave dataset.Stringname
Optional. Namespace of the Wave dataset.Stringnamespace
POST Request Body
Uses the same format as the GET and POST response body.
Analytics Notification
Save changes to a specific analytics notification (PUT) or delete one (DELETE).
Syntax
URI
/vXX.X/analytics/notifications/analytics notification ID
216
Analytics NotificationAnalytics Notifications API Resource Reference
Formats
JSON
HTTP methods
DescriptionMethod
Save changes to the analytics notification as specified in the request body.PUT
Delete the analytics notification. Deleted notifications can't be recovered.DELETE
Parameters
DescriptionParameter
Required for GET calls. Specifies what kind of analytic notification to return. Valid values are:source
•lightningSubscribe — report subscriptions
•waveNotification — Wave notifications
Optional. Return notifications for a single record. Valid values are:recordId
•reportId— Unique report ID
•lensId— Unique Wave lens ID
PUT Request Body
A notification object with desired changes.
DescriptionTypeProperty
Indicates whether the notification is being sent (true) or not (false).Booleanactive
Describes details of a Wave notification. Only applicable when source is
waveNotification.
WaveConfiguration[]configuration
Date and time when the notification was created (in ISO 8601 format).DateTimecreatedDate
Indicates whether the notification is deactivated after it's sent (true) or not
(false). Deactivation doesn't delete the notification.
The default value is false.
BooleandeactivateOnTrigger
Unique notification ID.Stringid
Date and time when the notification was last modified (in ISO 8601 format).DateTimelastModifiedDate
Display name of the notification.Stringname
Unique ID of the record that the notification describes. Valid values are:StringrecordId
•reportId
•lensId
217
Analytics NotificationAnalytics Notifications API Resource Reference
DescriptionTypeProperty
Details about the notification's schedule.Schedule[]schedule
Indicates the type of notification. Possible values are:Stringsource
•lightningSubscribe — report subscriptions
•waveNotification — Wave notifications
Specifies what happens when the notification runs. For example, sending an
email with report results.
Threshold[]thresholds
Schedule
DescriptionTypeProperty
How frequently the notification is invoked. Possible values are:Stringfrequency
•daily — Every day
•weekly — One or more days each week
•monthly — One or more days each month
Only necessary when frequency is monthly. Possible values are:StringfrequencyType
•relative — Days which can change month-to-month, as described
by details.
•specific — Fixed monthly dates, as described by details.
Describes the notification schedule. Varies depending on whether
frequency is daily, weekly, or monthly.
ScheduleDetail[]details
ScheduleDetail (frequency is daily)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
ScheduleDetail (frequency is weekly)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
The days of the week on which the notification is invoked. Possible values
are:
String[]daysOfWeek
•mon — Monday
•tue — Tuesday
218
Analytics NotificationAnalytics Notifications API Resource Reference
DescriptionTypeProperty
•wed — Wednesday
•thu — Thursday
•fri — Friday
•sat — Saturday
•sun — Sunday
ScheduleDetail (frequency is monthly, frequencyType is relative)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
The week in the month during which the notification is invoked. Possible
values are:
StringweekInMonth
•first — First week
•second — Second week
•third — Third week
•fourth — Fourth week
The day of the week on which the notification is invoked. Possible values
are:
StringdayInWeek
•mon — Monday
•tue — Tuesday
•wed — Wednesday
•thu — Thursday
•fri — Friday
•sat — Saturday
•sun — Sunday
•weekday — Weekday
•weekend — Weekend day
ScheduleDetail (frequency is monthly, frequencyType is specific)
DescriptionTypeProperty
The hour of the day at which the notification is invoked. Possible values
are integers from 0 to 23.
Integertime
The days of the month on which the notification is invoked. Possible values
are integers from 1 to 31, and -1 (which represents the last day of the
month).
Integer[]daysOfMonth
219
Analytics NotificationAnalytics Notifications API Resource Reference
Threshold
DescriptionTypeProperty
Specifies when the notification is invoked (other than date and time criteria).
Possible values are:
Stringtype
•always — Always invoke the notification
•onError — Invoke the notification when there is an error
•condition — Invoke the notification based on criteria described by
conditions
Describes conditions that govern when the notification is invoked.Condition[]conditions
Specifies what action is taken when the notification is invoked.Action[]actions
Condition
DescriptionTypeProperty
The data field which is operated on.StringcolName
The comparison value which is used by the operation.Stringvalue
The operation which is used to evaluate the condition. Possible values are:Stringoperation
•equal — colName and value are equal
•notEqual — colName and value are not equal
•greaterThan — colName is greater than value
•lessThan — colName is less than value
•greaterThanEqual — colName is greater than or equal to
value
•lessThanEqual — colName is less than or equal to value
Action
DescriptionTypeProperty
The type of action to perform when the notification is invoked. Possible
values are:
Stringtype
•sendEmail — Send an email to recipients
A basic configuration used for passing arguments to Apex pages.StringapexConfiguration
Returns null. Reserved for future use.Configconfiguration
220
Analytics NotificationAnalytics Notifications API Resource Reference
WaveConfiguration
DescriptionTypeProperty
Optional. The Id of the Wave dashboard widget to which the notification is
anchored.
Stringanchor
Optional. Description of selected filters at the time of notification creation.Stringfilter
Required. SAQL query which is run when the notification is invoked.Stringquery
Required. Collection of Wave datasets referenced by the notification.WaveDataset[]datasets
WaveDataset
DescriptionTypeProperty
Required. Id of the Wave dataset.Stringid
Optional. Developer name of the Wave dataset.Stringname
Optional. Namespace of the Wave dataset.Stringnamespace
PUT Response Body
An analytics notification object reflecting saved changes.
Uses the same format as the PUT request body.
DELETE Response Body
The analytics notification is deleted, and can't be recovered.
Returns an empty response body.
Analytics Notification Limits
Check to see how many more analytics notifications you can create.
Syntax
URI
/vXX.X/analytics/notifications/limits?source=waveNotification
Formats
JSON
221
Analytics Notification LimitsAnalytics Notifications API Resource Reference
HTTP methods
DescriptionMethod
Check how many analytic notifications you have, and the maximum number you can have.GET
Parameters
DescriptionParameter
Required for GET calls. Specifies what type of analytic notification to return limits for. Valid values are:source
•lightningSubscribe — report subscriptions
•waveNotification — Wave notifications
GET Response Body
DescriptionTypeProperty
How many analytics notifications of the type specified by source the user
is allowed to create.
Integermax
How many more analytics notifications of the type specified by source the
user can create before hitting the limit.
Integerremaining
222
Analytics Notification LimitsAnalytics Notifications API Resource Reference
INDEX
A
Analytics Notifications API
GET a list of analytics notifications 111, 115
GET a list of report types 46
Analytics Notifications API Examples
DELETE delete an analytics notification 115
POST create an analytics notification 113
PUT save an analytics notification 114
D
Dashboards API
filtering results 79
getting dashboard metadata 100
getting list of dashboards 75
getting results 75
getting status 80
refreshing 81
returning details about dashboard components 85
saving a dashboard 81
E
Examples Reports API 3
Examples: Dashboards API 74
I
Introduction 1
R
Reference
Dashboard error codes 209
Dashboard List 191
Dashboard Results 191
Dashboard Status 191
Notifications 211
Report Describe 117
Report Execute 117
Report Instances 117
Report List 117
Report Types 175
Reports and Dashboards REST API
report-level errors 172
Reports API Examples
POST create a report 4
Requirements and limitations 2
Resources
DELETE analytics notification 216
DELETE report 118
Detailed results 57, 143
Fact map 57
Filter report results 57, 143
GET analytics notifications limits 221
GET analytics notifications list 212
Get basic report metadata 129
GET dashboard describe 202
GET dashboard list 192
GET dashboard results 192
GET dashboard status 207
Get extended report metadata 129
Get recent reports list 157
GET report data 57, 143
GET report instance results 155
GET report instances 154
GET report type list 176
GET report type metadata 176
PATCH report 118
POST analytics notifications list 212
POST report data 57, 143
POST report instance 150, 154
POST Report Query Resource 161
PUT analytics notification 216
run report asynchronously 150
Summary level results 57, 143
S
Salesforce Reports and Dashboards REST API
asynchronous 51–52
dashboard, clone 108
dashboard, delete 109
filter reports 52
GET request 34, 42, 51
list report runs 51
POST request 52
recently viewed 55
report data 34
report list 55
report metadata 42
report, clone 72
report, delete 73
report, query 59
report, save 71
223
Salesforce Reports and Dashboards REST API (continued)
synchronous 52
224
Index

Navigation menu