{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper: Ad Reach By Region & Age", "description": "Extract ad data with the Facebook Ads Library Scraper. Retrieve active and inactive ads, creatives, targeting info, impressions, and engagement metrics. Perfect for competitor analysis, market research, and ad strategy insights. Fast, reliable, and scalable for bulk ad data extraction.", "version": "0.1", "x-build-id": "OoemdiBzLQFb96Kc7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapier~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapier-facebook-ads-library-scraper", "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/scrapier~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-scrapier-facebook-ads-library-scraper", "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/scrapier~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-scrapier-facebook-ads-library-scraper", "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": { "adPageUrls": { "title": "๐ŸŽฏ Advertiser pages / Ad Library URLs", "type": "array", "description": "๐Ÿ“‹ One entry per line โ€” a Facebook Page URL or an Ad Library query link. You may also pass objects with a `url` field (plus optional `label`, `limit`, or `period` per source).", "items": { "type": "string" } }, "maxAds": { "title": "๐Ÿ“ฆ Ads to profile (sample size)", "minimum": 1, "maximum": 50000, "type": "integer", "description": "๐Ÿ“ˆ Maximum number of ads to profile for reach & audience **across all advertisers** in this run. โฑ๏ธ Smaller = quick reach snapshot; ๐Ÿ“š larger = deeper audience coverage. Example: 25.", "default": 10 }, "reachSummaryOnly": { "title": "๐Ÿงพ Advertiser reach rollup only", "type": "boolean", "description": "๐Ÿ“‰ Skip per-ad detail and emit **one rollup row per advertiser** with just the total ad count โ€” a fast way to size an advertiser before a full audience pull. Default is off (one row per ad).", "default": false }, "deepTransparencyLookup": { "title": "๐Ÿ”ฌ Deep per-ad transparency lookup", "type": "boolean", "description": "๐Ÿ” Runs the extra per-ad Ad Library transparency request that carries EU reach, age/country/gender demographics and funder/spend data (โณ slower, far richer rows). Turn off only for a bare listing pass. Default is on.", "default": true }, "includeAdvertiserProfile": { "title": "๐Ÿข Attach advertiser page profile", "type": "boolean", "description": "๐Ÿ“„ For **Facebook Page** advertisers, attach the public page title/description snippet so you can see who is behind the reach. Default is off.", "default": false }, "includeAudience": { "title": "๐Ÿ‘ฅ Include EU reach & audience breakdown", "type": "boolean", "description": "๐Ÿ“ˆ When on, each row adds `euTotalReach`, `ageGenderCountryBreakdown` (perโ€‘country ร— age ร— gender reach) and `targeting` (ages/gender/locations reached). Requires the perโ€‘ad detail lookup (enabled automatically). Default is on.", "default": true }, "includeAudienceAnalytics": { "title": "๐Ÿ“ˆ Include audience analytics (derived)", "type": "boolean", "description": "๐Ÿงฎ When on, each row adds an `audienceAnalytics` object computed purely from the live EU reach data: `reachTier` (bucketed reach), `topCountry`, `countryCount`, `genderSkew` (male/female share + skew), `dominantAgeRange` and `ageSkew`. 100% coverage on EUโ€‘served ads โ€” real math on real reach numbers, never fabricated. Default is on.", "default": true }, "politicalOnly": { "title": "โš–๏ธ Political & issue ads only", "type": "boolean", "description": "๐Ÿ›๏ธ Keep only ads that carry political/issue transparency (funder/payer, beneficiary, spend or impressions ranges, or AAA eligibility). Example: turn on to export just the funded political ads from a broad Ad Library query. Default is off (all ads).", "default": false }, "targetCountry": { "title": "๐ŸŒ Reach country focus", "enum": [ "ALL", "AR", "AU", "AT", "BD", "BE", "BR", "CA", "CL", "CN", "CO", "CR", "CZ", "DK", "EC", "EG", "FI", "FR", "DE", "GR", "GT", "HK", "HU", "IN", "ID", "IE", "IL", "IT", "JP", "KE", "MY", "MX", "NL", "NZ", "NG", "NO", "PK", "PA", "PE", "PH", "PL", "PT", "PR", "RO", "RU", "SA", "SG", "ZA", "KR", "ES", "SE", "CH", "TW", "TH", "TR", "AE", "GB", "US", "UY", "VE", "VN", "UA" ], "type": "string", "description": "๐Ÿ“ Country used to pull reach for **Facebook Page** advertisers. Ad Library query links usually already carry their own country.", "default": "ALL" }, "dateRange": { "title": "๐Ÿ—“๏ธ Reach delivery window", "pattern": "^$|^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$", "type": "string", "description": "โณ Optional delivery window for Page advertisers when the source URL does not set one. **Leave empty** to follow the Ad Library default. Pick a calendar date or a relative span (e.g. 30 days) โ€” passed through as provided.", "default": "" }, "adStatus": { "title": "๐Ÿšฆ Ad delivery status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "๐ŸŽ›๏ธ Which ads to profile for **Page** advertisers (or when your Ad Library link leaves it unspecified): still-running, stopped, or both.", "default": "all" }, "proxyConfiguration": { "title": "๐Ÿ›ก๏ธ Proxy (optional)", "type": "object", "description": "๐Ÿ  Leave off for a standard run. If you enable Apify Proxy here, **only residential** proxy traffic is used for the whole run. Requires proxy access on your Apify plan." } } }, "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 } } } } } } } } } }