Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

  1. Send a request to /ReportExport with 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.

  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.

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:

Date range ended
Cached for

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 /ReportExport request. A job that is still QUEUED or RUNNING can't be replayed, and the request returns ERROR. A completed job can't be replayed until 60 minutes after it completes.

  • Don't call /ReportExport again 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 CACHED and doesn't re-run the job.

  • Replaying a FAILED or CANCELLED job within 15 minutes returns ERROR.

  • Replaying a job that is still QUEUED or RUNNING returns ERROR.

  • 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 QUEUED or RUNNING, and /Jobs/{Id}/Download returns the job status instead of the file. Check that the status is COMPLETED before 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 /ReportExport calls 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

How long are results available for download?

You can download the result for as long as the job exists. An identical request returns the same job, which refreshes on the cache rules above, so the file can change between runs. Once the date range ended more than 90 days ago, the file no longer changes.

When should I use the Replay function?
  • FAILED or CANCELLED jobs (15 minutes or more after the failure)

  • Re-running a completed job when you expect new data. Replay follows the same cache rules as an identical /ReportExport request, so it doesn't return fresher data than re-sending the request would.

How often can I poll for a job's status?

There is no specific limit on polling, but you can use webhooks (postbacks) to avoid excessive calls and receive real-time updates.

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

Identical parameters always map to the same job, so you get the same job ID. While the cache period is running, you get the cached result. When the cache period ends, the same job re-runs under the same job ID with fresh data (see the cache rules above).

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

Can I retrieve custom reports via API?

No. Custom reports built in Data Lab can't be retrieved via API. To get custom report data out of the platform, you can download the report directly, schedule it for email delivery, or share it with other users.

How do I know which reports I can retrieve via API?

API access is set per report and can change over time. To see which reports you can currently retrieve via API, see Check a Report's API Availability.

Last updated