Salesforce Reports and Dashboards REST API Developer Guide

Salesforce Reports and Dashboards REST API lets you programmatically access your report and dashboard data. This API lets you integrate the data into any web or mobile application, inside or outside the Salesforce platform. For example, you might use the API to trigger a Chatter post with a snapshot of top-performing reps each quarter.

PDF

Document

Salesforce Reports and
Dashboards REST API
Developer Guide
Version 41.0, Winter ’18
@salesforcedocs
Last updated: September 21, 2017

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

CONTENTS
Chapter 1: Salesforce Reports and Dashboards REST API . . . . . . . . . . . . . . . . . . . . . . . 1
Requirements and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Chapter 2: Examples: Reports REST API Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Create a New Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Run Reports Synchronously or Asynchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Get Report Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Get a List of Report Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
List Asynchronous Runs of a Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Filter Reports on Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
List Recently Viewed Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Decode the Fact Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Get Report Data without Saving Changes to or Creating a Report . . . . . . . . . . . . . . . . . . . . . 58
Save Changes to Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Clone Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Delete Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Chapter 3: Examples: Dashboards REST API Resources . . . . . . . . . . . . . . . . . . . . . . . 73
Get List of Recently Used Dashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Get Dashboard Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Filter Dashboard Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Get Dashboard Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Refresh a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Save a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Set a Sticky Dashboard Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Return Details About Dashboard Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Get Dashboard Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Clone a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Delete a Dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Chapter 4: Examples: Analytics Notifications REST API . . . . . . . . . . . . . . . . . . . . . . . . 110
Get Analytics Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Create an Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Save Changes to an Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Delete an Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Check Limits for Analytics Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Chapter 5: Reports API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Execute Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Execute Async . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Instances List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Instance Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Report List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Report Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Report Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Chapter 6: Report Types API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Report Type List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Report Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Chapter 7: Filter Operators API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . 204
Filter Operator List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Chapter 8: Dashboards API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Dashboard List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Dashboard Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Dashboard Describe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Dashboard Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Dashboard Filter Options Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Dashboard and Component Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Chapter 9: Analytics Notifications API Resource Reference . . . . . . . . . . . . . . . . . . . . 234
Analytics Notification List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Analytics Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Analytics Notification Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Chapter 10: Analytics Folders API Resource Reference . . . . . . . . . . . . . . . . . . . . . . . 247
Folder Share Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Folder Shares . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Folder Share by ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Folder Share Recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Contents

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

Key features

Integrate report data into custom objects
Define rich visualizations
Build custom dashboards
Automate reporting tasks

Frequently asked questions

The API is available for any organization that has API enabled. You must establish an authenticated session using OAuth in order to access the API.

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.

Your organization can request up to 1,200 asynchronous requests per hour. Asynchronous report run results are available within a 24-hour rolling period.

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

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

User questions

John L.

Why does the Salesforce Reports and Dashboards REST API return the error 'The component can't be displayed because the field(s) you chose for the filter are unavailable'?

This error is caused by using unsupported filter types with the Salesforce Reports and Dashboards REST API. Cross filters, standard report filters, and row limit filters are not supported. Ensure your filter settings are compatible with the API.

Michael O.

Why might a report definition become obsolete?

Changes to the underlying custom object or its relationships can cause a report definition to become obsolete. This may be due to administrator actions disabling reports for the object.