Synchronous Reports

What is a synchronous report?

A synchronous report is a small report that must run very quickly. Upon receiving a request to run a synchronous report, the DCM reporting platform will begin executing it for you immediately. Reports like these are best used in situations where you need a small chunk of data quickly, such as when you are displaying metrics in a graphical user interface.

What is the difference between synchronous and asynchronous report generation?

Running a report asynchronously will always take at least a few minutes, even if you are requesting a small amount of data. Synchronous reports return this data much faster at the cost of putting a low timeout on how long the report can take to run. You should use asynchronous report generation when the report cannot be run within the synchronous timeout period or when you’re not in a time-sensitive environment such as a user interface.

What is the synchronous report timeout period?

If the report is small enough to run in 10 seconds or less, the system will return a complete report file to your initial run request. Otherwise, DCM reporting will execute your report for a period of 50 seconds before timing out.

What happens if a synchronous report takes too long?

If the generation of a synchronous report does not complete within the timeout period, the generation is halted and the report fails over into our asynchronous reporting queue. Your report will not fail or return an error, but moving into the asynchronous reporting queue means that your report will now take at least a few minutes to generate.

You will receive no indication that your report exceeded the synchronous reporting timeout period other than the report’s generation time. It will either complete synchronously in 50 seconds or less or become asynchronous and require several minutes.

Which report types support synchronous execution?

All report types support synchronous execution with the exception of:

The other report types all support synchronous execution but will still timeout if too much data or a resource-intensive mix of metrics and dimensions are used.

How do I run a synchronous report?

By default, all reports run asynchronously. When requesting the generation of a new report file, you can set the optional synchronous parameter to true to request the report be run synchronously. Refer to the example code in our documentation.

Should I request all my reports with synchronous execution?

No, you should only request synchronous execution when you expect the report to finish within the timeout period. If your report starts with synchronous execution and hits the timeout limit, the report will be moved to the asynchronous queue—the report's total execution time will be the time required to generate the report asynchronously plus the synchronous timeout period. Thus, if you had requested the report asynchronously, you would have avoided the additional delay of the synchronous timeout period.

Will the metrics and dimensions I request affect the generation time of my reports?

Yes, they will. Certain metrics and dimensions take longer to compile than others and some of them may even cause your synchronous reports to always timeout. Geographical dimensions are one such dimension that will rarely, if ever, be fast enough to include in synchronous reports.

How can I shorten the time needed to generate my reports to allow synchronous reporting?

Many factors, such as the size of the campaigns included and the timespan that the report covers, affect speed. A bit of manual tweaking is often the best way to get your reports down to small enough chunks—start with everything you want to be able to display quickly, and then try whittling the report down until it successfully completes synchronously.