# Pinterest Ads Library Scraper (`khadinakbar/pinterest-ads-library-scraper`) Actor Search Pinterest's public Ads Repository by market, date, advertiser, category, age, or gender. Export source-linked ad creatives, flight dates, disclosed targeting, and reach ranges for competitive research. Charged $0.006 per saved ad plus platform usage. - **URL**: https://apify.com/khadinakbar/pinterest-ads-library-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, Automation, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $6.00 / 1,000 pinterest ad scrapeds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Pinterest Ads Library Scraper Pinterest Ads Library Scraper turns a bounded search of Pinterest's public Ads Repository into source-linked, normalized dataset records. Use it to research which creative is visible in a supported market, when an ad ran, and which targeting and reach ranges Pinterest publicly discloses. The output is designed around the repository's public creative and disclosure fields. ### Best fit and scope Choose this Actor for a quick competitor creative audit, agency swipe-file refresh, market research, or a reproducible input for an AI workflow. It is best for one supported market and a date window no wider than 31 calendar days. For organic Pin discovery, creator research, or private advertising-account reporting, start with a focused Pinterest Pin or profile workflow that uses the appropriate public source. ### Focused standalone workflow This Actor works as a focused standalone workflow for public ad-repository research. An agency analyst starts with a named advertiser and one market, exports the saved records, then compares source-linked creative, flight dates, and disclosed reach ranges in a reporting sheet. Next, the strategist can feed the resulting creative themes into an approved content brief or media-planning process. ### Quick start ```json { "country": "FR", "startDate": "2026-08-01", "endDate": "2026-08-10", "advertiserName": "Tommy Hilfiger", "category": "ALL", "gender": "ALL", "age": "ALL", "maxResults": 10 } ``` `country` selects the repository market; `advertiserName`, `category`, `gender`, and `age` are optional public filters. `maxResults` is capped at 24 because that is the repository page boundary. Start with a narrow date range and a small result cap, inspect the dataset, then repeat an exact input when you need a reproducible comparison. ### Output Each saved item is a validated public ad record. Empty arrays mean that Pinterest did not disclose a field, not that the Actor inferred a value. | Field | Meaning | | ------------------------------------------------------------------- | ------------------------------------------------------- | | `adId` / `repositoryUrl` | Pinterest public repository identifier and source link. | | `advertiserName`, `title`, `creativeText` | Public advertiser and bounded creative copy. | | `imageUrl`, `videoUrl` | Public creative assets when Pinterest exposes them. | | `startDate`, `endDate` | Public ad flight dates when disclosed. | | `targetCountries`, `targetAgeBuckets`, `targetGenders`, `interests` | Public targeting disclosures, not inferred targeting. | | `audienceReachEu`, `audienceReachByCountry` | Publicly disclosed reach ranges. | | `source`, `scrapedAt` | Provenance and extraction time. | ```json { "adId": "4606126974742064000", "repositoryUrl": "https://ads.pinterest.com/ads-repository/?pin_id=4606126974742064000", "country": "FR", "advertiserName": "Tommy Hilfiger", "title": "Bottes Western En Cuir À Logo Gaufré", "imageUrl": "https://i.pinimg.com/...jpg", "startDate": "2026-07-27", "endDate": "2026-08-06", "targetCountries": ["France"], "targetAgeBuckets": ["18+"], "targetGenders": ["FEMALE", "MALE"], "audienceReachEu": "0 - 10000", "source": "pinterest_ads_repository", "scrapedAt": "2026-08-10T12:00:00.000Z" } ``` The Actor also writes `OUTPUT` and `RUN_SUMMARY` to the default key-value store. Read `OUTPUT.outcome` before downstream automation: `COMPLETE` means all fetched records were persisted, `PARTIAL` means usable data with warnings, `VALID_EMPTY` means the public repository returned no matching rows, and `INVALID_INPUT` identifies a fixable input issue. An inaccessible public repository with no useful records is reported as `UPSTREAM_FAILED` rather than a fabricated empty success. ### Pricing and cost boundary Pay per event is enabled with platform usage passed through to the user. An Actor start costs $0.00005 per allocated GB (one-event minimum), and every validated saved ad costs $0.006. A ten-ad example has at most $0.06005 in named event charges before Apify platform usage. The Actor logs this cap before the first record event; check the live Pricing tab for the current platform component. ### Run through the Apify API ```bash curl -X POST "https://api.apify.com/v2/acts/khadinakbar~pinterest-ads-library-scraper/runs?token=YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"country":"FR","startDate":"2026-08-01","endDate":"2026-08-10","advertiserName":"Tommy Hilfiger","maxResults":10}' ``` ### AI-agent prompt > Use this Pinterest Ads Library Scraper AI agent workflow to collect up to 10 public Pinterest Ads Repository records for France. Keep `repositoryUrl`, `source`, and `scrapedAt` with the dataset export, read `OUTPUT.outcome` as a dataset readback before analysis, and use the documented cost and scope boundary when interpreting public reach ranges. ### Best-results guidance Use the exact advertiser name Pinterest exposes and pair one market with a focused date window. Keep the source URL with every benchmark, schedule the same bounded input when freshness matters, and compare disclosed fields as the public repository presents them. ### Builder's note I built this Actor around an anonymous browser session before calling the public repository route. I designed the record contract to retain a clear source path, validate every persisted row, and make the terminal outcome useful to an automation that needs current public-ad evidence. ### Responsible use Use public repository data responsibly, respect Pinterest's terms and applicable law, and treat disclosed demographic ranges as aggregate transparency fields rather than personal data or a basis for sensitive targeting. This independent Actor is not affiliated with Pinterest. # Actor input Schema ## `country` (type: `string`): Select the supported Pinterest repository market used to find disclosed ads, for example FR for France. Use a two-letter country code from the list. Defaults to FR for a working public repository search. This is not your billing country or proxy-location setting. ## `startDate` (type: `string`): Set the inclusive beginning of the public repository window in YYYY-MM-DD format, for example 2026-08-01. Defaults to seven days before the run begins when omitted. The maximum window is 31 calendar days. This is not a relative date phrase or an ad creation-date guarantee. ## `endDate` (type: `string`): Set the inclusive end of the public repository window in YYYY-MM-DD format, for example 2026-08-10. Defaults to the run date when omitted. It must be on or after startDate and within the 31-day window. This is not an overall Actor timeout. ## `advertiserName` (type: `string`): Optionally narrow the public repository to a disclosed advertiser name, for example Tommy Hilfiger. Leave blank to browse the selected market and date window. Names are matched by Pinterest's repository and may not be exact. This is not a Pinterest username, ad ID, or private account ID. ## `category` (type: `string`): Optionally filter by Pinterest's public ad category, for example HOME\_DECOR. Defaults to ALL and only controls the repository filter. Use it for category-level creative research, not to classify the returned creative yourself. This is not a free-text keyword search. ## `gender` (type: `string`): Optionally apply the repository's disclosed gender filter: ALL, FEMALE, MALE, or UNSPECIFIED. Defaults to ALL. It reflects Pinterest's public ad-library filter rather than inferred user demographics. This is not a guarantee that every returned ad targets only that gender. ## `age` (type: `string`): Optionally apply Pinterest's public age-bucket filter, for example AGE\_25\_34. Defaults to ALL. Use the public filter values exactly as shown. This is not an inferred audience-age estimate or a free-text age range. ## `maxResults` (type: `integer`): Cap the validated public ad records saved to the dataset. Enter an integer from 1 to 24; the default is 24 and each saved record charges the ad-scraped event. Keep it low for a quick evidence check. This is not a guarantee that Pinterest has that many matches. ## `requestTimeoutSecs` (type: `integer`): Set the browser navigation and public repository request timeout in seconds. Enter 20 to 120; the default is 60. Increase it only for a slow public response, not to bypass access controls. This is not the whole Actor run timeout. ## Actor input object example ```json { "country": "DE", "startDate": "2026-08-01", "endDate": "2026-08-10", "advertiserName": "Tommy Hilfiger", "category": "HOME_DECOR", "gender": "FEMALE", "age": "AGE_25_34", "maxResults": 10, "requestTimeoutSecs": 60 } ``` # Actor output Schema ## `ads` (type: `string`): Validated source-linked public ad records with creative, dates, targeting, and reach fields. ## `summary` (type: `string`): Compact terminal outcome with saved count, warnings, and named event counters. ## `runSummary` (type: `string`): Detailed terminal telemetry and safe diagnostics for monitoring or support. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "country": "FR", "category": "ALL", "gender": "ALL", "age": "ALL", "maxResults": 5 }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/pinterest-ads-library-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "country": "FR", "category": "ALL", "gender": "ALL", "age": "ALL", "maxResults": 5, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/pinterest-ads-library-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "country": "FR", "category": "ALL", "gender": "ALL", "age": "ALL", "maxResults": 5 }' | apify call khadinakbar/pinterest-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/pinterest-ads-library-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/oKsJ4mO6RAVbvcrnz/builds/6gevccJbhawiTr95g/openapi.json