Send a POST to /{ad_account_id}/insights with the async parameter set to true along with your desired fields, time_range, breakdowns, and level; the API returns a report_run_id immediately.
Use the report_run_id to poll GET /{report_run_id} periodically; check the async_status field which progresses through 'Job Not Started', 'Job Running', and 'Job Completed' (or 'Job Failed').
Implement exponential backoff in your polling loop, starting at a few seconds and increasing to minutes for long-running reports; avoid polling more frequently than every 30 seconds for large reports.
Once async_status is 'Job Completed', fetch results from GET /{report_run_id}/insights with pagination; use the cursor-based after token to retrieve all result pages.
Handle 'Job Failed' status by logging the error details returned in the report run object and re-queuing the request; common causes include invalid field combinations or breakdown restrictions.
Be aware that certain breakdown combinations involving reach metrics are restricted for date ranges older than 13 months as of June 2025; avoid these combinations for historical reports.
Known gotchas
Reach breakdowns with start_date more than 13 months old no longer return data as of June 10, 2025; requests that include reach with these date ranges will either return empty data or an error rather than historical reach figures.
The report_run_id is ephemeral and results are only available for a limited time window after completion (check current docs for the TTL); cache the final results to persistent storage before the window expires.
Async Insights results are rate-limited separately from synchronous Insights calls; issuing many async report requests in parallel can still exhaust BUC quota — stagger submissions and track outstanding job counts.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp