Skip to main content
The report endpoints return the same data as a downloadable file. Use them for anything destined for a spreadsheet, a warehouse, or a scheduled email, rather than paginating through breakdowns and reassembling the result.
date_from and date_to are required. granularity and metric narrow what the report contains; the campaign report also accepts timezone.
These endpoints return a file, not the usual {"data": ...} envelope. Write the body to disk rather than parsing it as JSON — and if you get JSON back, that is an error envelope worth reading.

A monthly export

Reports and retention

Reports read the same data as everything else, so the same retention floor applies — and because you get a file rather than an envelope, there is no retention notice to warn you. A report for a range older than your window will simply start later than you asked. Check the floor from get_organization_plan_summary before requesting a long historical export, and treat the first row of the file as the real start date.

Practical notes

Whole months or weeks concatenate cleanly. Overlapping ad-hoc ranges have to be de-duplicated by whoever inherits the spreadsheet.
A wide export is real work. Allow a generous client timeout rather than retrying — a retry doubles the load and usually times out too.
They are ordinary requests. A nightly job exporting per-campaign reports across hundreds of campaigns needs the same pacing as any other loop. See Rate limits.
Day boundaries are UTC unless you say otherwise, which shifts every daily figure for a non-UTC audience.