Salesforce Reports and Dashboards REST API Developer Guide

Overview
Examples
Reports Examples
Create a New Report
Run Reports Synchronously or Asynchronously
Get Report Metadata
Get a List of Report Types
Download Formatted Excel Reports Using the Reports REST API
List Asynchronous Runs of a Report
Filter Reports on Demand
List Recently Viewed Reports
Decode the Fact Map
Get Report Data without Saving Changes to or Creating a Report
Save Changes to Reports
Clone Reports
Delete Reports
Dashboards Examples
Downloads Examples
Notifications Examples
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

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.

Example of an asynchronous report run

  1. This is a POST request (an empty request body), /services/data/v35.0/analytics/reports/00OR0000000K2UeMAK/instances, to the Execute Async resource for an asynchronous run requesting summary results.

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

  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.