Pinterest Ads Library Scraper

Pinterest Ads Library Scraper

Collect structured, public advertisement-transparency records from Pinterest's official Ads Repository. The Actor uses the public repository page and its public resource endpoints; it does not log in, bypass access controls, solve CAPTCHAs, or accept Pinterest credentials.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

What it returns

Normal rows use entityType: "pinterest_ad" and contain the public ad or Pin ID, canonical Pin URL, advertiser identity when available, creative text and media, destination URL and domain, campaign dates, audience targeting, reach ranges, transparency flags, the requested filters, and source position. Optional fields are omitted when Pinterest does not publish them. Rows are deduplicated by Pin ID.

If Pinterest returns no usable rows or access is blocked, the Actor emits one diagnostic row with exactly url, error, errorCode, and scrapedAt. The diagnostic is not ad data. The OUTPUT_SUMMARY key-value record contains run status, counts, filters, pagination, detail-request, and completion information.

Input

Field	Type	Default	Description
advertiserName	string	none	Optional public advertiser-name filter, such as Nike.
country	string	FR	Supported repository country code.
startDate	YYYY-MM-DD	five days ago	Start of the date window forwarded to Pinterest's Ads Repository API.
endDate	YYYY-MM-DD	run date	End of the date window forwarded to Pinterest's Ads Repository API; the range may be at most 30 days.
vertical	string	none	Optional Ads Repository category/vertical, such as BEAUTY.
gender	enum	none	FEMALE, MALE, or UNSPECIFIED.
ageBucket	enum	none	Pinterest API value such as AGE_18_24.
maxItems	integer	10	Maximum normal ad rows, from 1 to 50.
maxPages	integer	3	Maximum bookmark pages, from 1 to 10.
includePinDetails	boolean	true	Enrich rows with public Pin media, attribution, and destination data when available.
maxDetailItems	integer	10	Maximum Pin-detail requests, from 0 to 50.
requestDelayMs	integer	250	Delay before each page after the first, from 0 to 10000 ms.
maxConcurrency	integer	1	Bounded crawler concurrency, from 1 to 2.
maxRequestRetries	integer	1	Bounded navigation retries, from 0 to 3.
requestTimeoutSecs	integer	60	Navigation/handler timeout, from 10 to 180 seconds.
proxyConfiguration	object	direct	Optional Apify or custom proxy configuration. Credentials are not written to output.

The runtime also accepts legacy query as an alias for advertiserName and category as an alias for vertical; supplying both names in either pair is rejected. Pinterest's currently exposed country filters are AT, BE, BR, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, NO, PL, PT, RO, SK, SI, ES, SE, and TR.

Example input

{
  "advertiserName": "Nike",
  "country": "FR",
  "startDate": "2026-09-02",
  "endDate": "2026-09-07",
  "maxItems": 10,
  "maxPages": 3,
  "includePinDetails": true,
  "proxyConfiguration": { "useApifyProxy": false }
}

Output example

Values depend on the public repository at run time. A normal row has this shape:

{
  "entityType": "pinterest_ad",
  "adId": "4602397446275423616",
  "pinId": "4602397446275423616",
  "pinUrl": "https://www.pinterest.com/pin/4602397446275423616/",
  "advertiserName": "Example advertiser",
  "adTitle": "Example campaign",
  "destinationUrl": "https://example.com/offer",
  "imageUrl": "https://i.pinimg.com/474x/example.jpg",
  "mediaType": "image",
  "countries": ["France"],
  "contentCommercial": true,
  "searchUrl": "https://ads.pinterest.com/ads-repository/?country=FR",
  "pageNumber": 1,
  "itemPosition": 1,
  "scrapedAt": "2026-09-07T12:00:00.000Z"
}

Running locally

npm install
apify run --purge --input-file qa-inputs/pinterest-ads-library-scraper/local-primary.json
npm test
npm run validate

The scraper follows the Ads Repository's bookmark pagination up to maxPages and stops at maxItems. Direct access is the default; enable standard Apify Proxy only when needed for a permitted request. Website availability and published transparency fields can change, so consumers should tolerate absent optional properties and use the data lawfully under Pinterest's terms and applicable regulations.

Date-window semantics

The Actor forwards startDate and endDate unchanged to Pinterest's public Ads Repository API as start_date and end_date, and records the effective values in OUTPUT_SUMMARY.dateFilter and each normal row's requestedStartDate/requestedEndDate. Pinterest's response fields startDate and endDate describe the returned ad's published campaign flight; they are not post-filtered by this Actor and may extend outside the requested API window. The public response does not expose the backend matching dimension, so the Actor does not claim that those campaign dates are a strict subset of the request.