Retrieve large Pinterest Ads reports with the async Reports API
domain: developers.pinterest.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Authenticate with an OAuth2 Bearer token scoped for ads reporting.
POST /ad_accounts/{ad_account_id}/reports with columns, start_date/end_date, granularity, level, and any attribution windows (click/engagement/view) you need.
Poll the same report-status endpoint until the report is marked ready.
Before trusting conversion numbers, check the metrics-ready-state endpoint, since conversion metrics may not be finalized when a report first completes.
Download the report from the returned URL promptly — generated report download links are time-limited and expire.
For recurring reports, use the report template endpoints to list and reuse saved report configurations instead of rebuilding the request each time.
Known gotchas
Download URLs expire on a documented job-expiry window; deferring the download after the report completes can leave you with a dead link.
Pulling conversion metrics before the metrics-ready-state check returns ready can give you numbers that later change.
Premiere Spotlight campaign spend is reported in UTC rather than the account's local time zone, which can split a single local calendar day's spend across two report rows.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?