Best Practices for Exporting Reports
This guide will help you optimize your ReportExport integration. Key topics include exporting reports efficiently, refreshing data when needed, and avoiding unnecessary API usage or rate-limit issues.
Job IDs created before November 9, 2026 no longer work. If an older job ID returns "not found", send the original /ReportExport request again to get a new job.
Implementation steps
Send a request to
/ReportExportwith your desired parameters.Identical requests return the same job. Until its cache period ends (see below), an identical request returns the cached result, so re-sending it early only uses up API calls.
Track the status of the job in one of two ways after submitting your export request:
Poll the
JobsAPI by using the URIs returned in the/ReportExportresponse to the call:GET /Jobs/{Id}.Enable a postback webhook to receive automatic notifications when your job is complete. This approach will significantly reduce the number of API calls.
Once the job reaches a
COMPLETEDstate, download the file by calling:/Jobs/{Id}/Download.
Identical requests (same parameters) return the same job. If that job has completed, you get the cached result until the cache period ends. The cache period depends on how long ago the report's date range ended:
Within the last day
60 minutes
1–5 days ago
8 hours
5–15 days ago
12 hours
15–30 days ago
18 hours
30–60 days ago
24 hours
More than 60 days ago
32 hours
After the cache period ends, the next identical request re-runs the same job, with the same job ID, to pick up new data. The downloaded file can therefore change between runs.
A report keeps refreshing until 90 days after its date range ends. After that, it runs one final time and then always returns the cached result. This is expected and is not an error.
Refresh report data
If you need refreshed or updated results for a previously completed job, use: /Jobs/{Id}/Replay.
Replay best practices
Only use replay when it is absolutely necessary. It should be reserved for cases where new or updated data is expected for the report, or the original job ended in a FAILED or CANCELLED state.
Don't replay a job immediately after submitting a
/ReportExportrequest. A job that is stillQUEUEDorRUNNINGcan't be replayed, and the request returnsERROR. A completed job can't be replayed until 60 minutes after it completes.Don't call
/ReportExportagain with the same parameters before the cache period ends. You'll get the cached result, and the call still counts toward rate limits.Avoid integrations that repeatedly trigger replays or re-run the same report multiple times per day.
How replays work
Replaying a completed job within 60 minutes of completion returns
CACHEDand doesn't re-run the job.Replaying a
FAILEDorCANCELLEDjob within 15 minutes returnsERROR.Replaying a job that is still
QUEUEDorRUNNINGreturnsERROR.Waiting 60 minutes doesn't guarantee that a Replay will run, because the cache rules above still apply.
While a job re-runs, its status goes back to
QUEUEDorRUNNING, and/Jobs/{Id}/Downloadreturns the job status instead of the file. Check that the status isCOMPLETEDbefore downloading.
For the most up-to-date data
To ensure completeness, request exports later in the day or the following day when the underlying datasets have been fully updated.
General tips
Use smaller date ranges when downloading reports to improve performance and avoid unnecessary large exports.
Avoid repeating
/ReportExportcalls with the same parameters before the cache period ends. Those calls return the cached result, count toward your API usage quota, and can lead to rate limiting.Only replay exports when data changes justify it.
Event postbacks
If you want to reduce the number of API calls required to track a job's progress, you can use event postbacks instead of polling the Jobs API.
With postbacks enabled, your system will automatically receive a notification when the job status changes, removing the need to repeatedly call GET /Jobs/{JobId}.
This alternative only replaces job-status polling; you will still use the ReportExport and Jobs APIs for submitting, replaying, and downloading reports.
Use event postbacks to be notified when updates are available, then trigger the appropriate API request to download the completed job. Learn how to enable postbacks to significantly reduce the volume of calls required and help to avoid rate-limit issues.
Frequently asked questions
Last updated

