{ "openapi": "3.0.1", "info": { "title": "Facebook & Instagram Ad Library Scraper (Meta)", "description": "Search every ad running on Facebook, Instagram, Messenger and Audience Network via Meta's official Ad Library API. Filter by keyword, page, country, date, platform and media type. Political ads include spend and impressions.", "version": "0.1", "x-build-id": "nKwLDTNwxJfuTqKZa" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/straightforward_hydra~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-straightforward_hydra-meta-ad-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/straightforward_hydra~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-straightforward_hydra-meta-ad-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/straightforward_hydra~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-straightforward_hydra-meta-ad-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", "required": [ "accessToken" ], "properties": { "accessToken": { "title": "Meta access token", "type": "string", "description": "Your own Meta access token. Create an app at developers.facebook.com, complete identity verification, then copy a token from the Graph API Explorer. Stored as a secret and sent only to Meta." }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords to search ad text for, e.g. \"nike\", \"black friday\". Each term is searched separately.", "default": [ "nike" ], "items": { "type": "string" } }, "pageIds": { "title": "Page IDs", "type": "array", "description": "Search specific advertiser pages by Facebook page ID instead of by keyword. Combined into one query.", "items": { "type": "string" } }, "countries": { "title": "Countries reached", "type": "array", "description": "ISO country codes the ad reached, e.g. US, GB, DE. Meta requires at least one.", "default": [ "US" ], "items": { "type": "string" } }, "adType": { "title": "Ad category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "ALL covers every ad. The other categories are Meta's regulated verticals — political/issue ads are the only ones that expose spend and impressions.", "default": "ALL" }, "adActiveStatus": { "title": "Active status", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Whether to include ads that have stopped running.", "default": "ALL" }, "mediaType": { "title": "Media type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "NONE" ], "type": "string", "description": "Restrict to a creative format.", "default": "ALL" }, "languages": { "title": "Languages", "type": "array", "description": "Restrict to ads in these languages, e.g. en, es, de.", "items": { "type": "string" } }, "deliveryDateMin": { "title": "Delivered from", "type": "string", "description": "Only ads delivered on or after this date (YYYY-MM-DD)." }, "deliveryDateMax": { "title": "Delivered to", "type": "string", "description": "Only ads delivered on or before this date (YYYY-MM-DD)." }, "includeSpendAndImpressions": { "title": "Include spend, impressions & demographics", "type": "boolean", "description": "Adds spend ranges, impression ranges, audience size and demographic breakdowns. Meta only releases these for political & issue ads — set Ad category to \"Political & issue ads\" as well, or the request is rejected.", "default": false }, "maxResults": { "title": "Max ads", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Total ads to collect, split evenly across your search terms.", "default": 100 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. The Graph API does not need a proxy.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } }