{ "openapi": "3.0.1", "info": { "title": "Pinterest Ads Scraper — Performance Analytics", "description": "Pinterest Ads Scraper extracts Pinterest advertising data, including promoted pins, ad details, advertiser information, engagement metrics, links, and creative data. Automate competitor research, ad monitoring, market analysis, and Pinterest campaign intelligence.", "version": "0.1", "x-build-id": "wbHYdHwkjEmhrNu9u" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/simpleapi~pinterest-ads-scraper-performance-analytics/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-simpleapi-pinterest-ads-scraper-performance-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/simpleapi~pinterest-ads-scraper-performance-analytics/runs": { "post": { "operationId": "runs-sync-simpleapi-pinterest-ads-scraper-performance-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/simpleapi~pinterest-ads-scraper-performance-analytics/run-sync": { "post": { "operationId": "run-sync-simpleapi-pinterest-ads-scraper-performance-analytics", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "targetMarket": { "title": "🌍 Target Market (Country)", "enum": [ "Austria", "Belgium", "Brazil", "Bulgaria", "Croatia", "Cyprus", "Czech Republic", "Denmark", "Estonia", "Finland", "France", "Germany", "Greece", "Hungary", "Ireland", "Italy", "Latvia", "Lithuania", "Luxembourg", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Slovakia", "Slovenia", "Spain", "Sweden", "Turkey" ], "type": "string", "description": "The Pinterest Ads Library market to analyze. Example: \"Germany\" → only ads that ran in Germany. Legacy alias: country." }, "dateFrom": { "title": "📅 Ad Flight Window — From", "pattern": "^(|\\d{4}-\\d{2}-\\d{2}|\\d+\\s*[hdwmyHDWMY])$", "type": "string", "description": "Start of the date range to search (YYYY-MM-DD absolute, or relative like 30d/6m/2y meaning \"X ago\"). Pinterest's public Ads Library lags real time significantly — recent windows often return 0 ads, so the default targets a period with confirmed real ad coverage. Legacy alias: start_date." }, "dateTo": { "title": "📅 Ad Flight Window — To", "pattern": "^(|\\d{4}-\\d{2}-\\d{2}|\\d+\\s*[hdwmyHDWMY])$", "type": "string", "description": "End of the date range to search (YYYY-MM-DD absolute, or relative like 30d/6m/2y meaning \"X ago\"). Default is a 14-day window ~2 years back where real ad data is confirmed to exist. Legacy alias: end_date." }, "maxAdsToAnalyze": { "title": "🔢 Max Ads To Analyze", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of ads to fetch and score (1–10,000). Legacy alias: resultsLimit." }, "includeTargetingBreakdown": { "title": "🎯 Flatten Targeting Fields", "type": "boolean", "description": "Flatten age/gender/interest/geo targeting into real output columns and compute targetingBreadthScore (0–5, count of non-empty targeting dimensions). Zero extra requests — this data is already fetched per ad.", "default": true }, "includePerformanceMetrics": { "title": "📈 Compute Reach & Duration Metrics", "type": "boolean", "description": "Compute reachMidpoint (numeric midpoint of Pinterest's disclosed reach RANGE — never a fabricated exact number) and adDurationDays from each ad's own flight dates. Zero extra requests.", "default": true }, "includeEngagementRate": { "title": "💬 Fetch Engagement Rate (1 extra request/ad)", "type": "boolean", "description": "Fetch each ad's public pin page to read saves/shares/comment counts and compute engagementRate = (saves+shares+comments) / reachMidpoint. Adds ONE extra request per ad. Real coverage is partial (Pinterest only exposes these stats on a fraction of ad pins) — null when unavailable, never a faked 0.", "default": true }, "start_date": { "title": "Legacy: Start Date", "pattern": "^(|(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))$", "type": "string", "description": "Legacy/compatibility field from the base actor (YYYY-MM-DD). Prefer dateFrom above. Used only when dateFrom is not supplied." }, "end_date": { "title": "Legacy: End Date", "pattern": "^(|(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))$", "type": "string", "description": "Legacy/compatibility field from the base actor (YYYY-MM-DD). Prefer dateTo above. Used only when dateTo is not supplied." }, "country": { "title": "Legacy: Country", "enum": [ "Austria", "Belgium", "Brazil", "Bulgaria", "Croatia", "Cyprus", "Czech Republic", "Denmark", "Estonia", "Finland", "France", "Germany", "Greece", "Hungary", "Ireland", "Italy", "Latvia", "Lithuania", "Luxembourg", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Slovakia", "Slovenia", "Spain", "Sweden", "Turkey", "United Kingdom", "United States" ], "type": "string", "description": "Legacy/compatibility field from the base actor. Prefer targetMarket above. Used only when targetMarket is not supplied." }, "resultsLimit": { "title": "Legacy: Results Limit", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Legacy/compatibility field from the base actor (1–10,000). Prefer maxAdsToAnalyze above. Used only when maxAdsToAnalyze is not supplied." }, "proxyConfiguration": { "title": "🔒 Proxy (Optional)", "type": "object", "description": "Enable if you experience access issues. Most users can leave this disabled." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }