API Reference
Start typing to search…

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.

Implementation steps

  1. Send a request to /ReportExport with your desired parameters.

    Important: Don't submit repeat requests with identical parameters. This will not refresh the data and will unnecessarily increase your API usage.

  2. Track the status of the job in one of two ways after submitting your export request:

    • Poll the Jobs API by using the URIs returned in the /ReportExport response 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.

  3. Once the job reaches a Completed state, download the file by calling: /Jobs/{Id}/Download.

    All completed job results are cached indefinitely, meaning your data will remain available for download at any time in the future.

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 /ReportExport request. The initial request may still be in the queue for processing and the data will not have changed, so the replay will provide identical results while unnecessarily increasing API usage.
  • Don't call /ReportExport again with the same parameters. This will not refresh the data and will count toward rate limits.
  • Avoid integrations that repeatedly trigger replays or re-run the same report multiple times per day.

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 repeated /ReportExport calls with the same parameters—these 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

How long are results available for download?

Results are currently stored indefinitely.

When should I use the Replay function?

Use replay for:

  • FAILED or CANCELLED jobs
  • Cases where additional data may now be available
  • Refreshing a report without changing parameters
Is there a limit to how often I can poll for a status?

No, there is no specific limiter on polling—but we recommend using webhooks to avoid excessive calls.

Why am I getting the same Job ID every time I call /ReportExport?

This happens because an identical request with the exact same parameters has already been submitted. When the system detects a duplicate request, it returns the existing JobId instead of creating a new job.

A new job will only be scheduled if you change one or more of the input parameters, or your query relies on default date ranges and a new calendar day has passed since the original request.

If you need updated results for a job that has already been executed, for example, if additional data has since become available, you can use /Jobs/{JobId}/Replay to refresh that job rather than submitting a new /ReportExport request.