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 noretention 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
Export on a boundary
Export on a boundary
Whole months or weeks concatenate cleanly. Overlapping ad-hoc ranges have to be de-duplicated by whoever inherits the spreadsheet.
Long ranges take time
Long ranges take time
A wide export is real work. Allow a generous client timeout rather than retrying — a retry doubles the load and usually times out too.
Reports count against your rate limit
Reports count against your rate limit
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.
Pass a timezone for the campaign report
Pass a timezone for the campaign report
Day boundaries are UTC unless you say otherwise, which shifts every daily figure for a non-UTC audience.