{ "openapi": "3.0.1", "info": { "title": "Facebook Hashtag Scraper - Ad Library Search by Hashtag", "description": "Search Meta Ad Library by hashtag. Returns matching ads, advertisers, creative assets, delivery details, and landing pages. MCP/API-ready.", "version": "1.0", "x-build-id": "niNlxfQkCwpLcXXVF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~facebook-hashtag-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-facebook-hashtag-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/khadinakbar~facebook-hashtag-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-facebook-hashtag-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/khadinakbar~facebook-hashtag-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-facebook-hashtag-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": [ "hashtags" ], "properties": { "hashtags": { "title": "Hashtags", "type": "array", "description": "List of hashtags to search the Facebook Ad Library for (e.g. ['#blackfriday', 'fitness']). The leading '#' is optional and added automatically; spaces inside a tag are removed ('#summer sale' becomes '#summersale'). Each hashtag is searched independently and matched against ad copy in the Meta Ad Library. This is NOT a Facebook page URL or username - to scrape a page's posts use a Facebook page scraper instead.", "items": { "type": "string" } }, "maxResultsPerHashtag": { "title": "Max ads per hashtag", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of ads to return for each hashtag (e.g. 50). The actor paginates through the Ad Library until it reaches this cap or runs out of results. Defaults to 50; range 1-1000. You are charged per ad returned, so this is also your per-hashtag cost cap.", "default": 50 }, "country": { "title": "Country", "type": "string", "description": "Two-letter ISO country code to scope ad delivery (e.g. 'US', 'GB', 'DE'), or 'ALL' for every country. Defaults to 'ALL'. This filters where the ads were shown, not the advertiser's location. Invalid codes fall back to 'ALL'.", "default": "ALL" }, "status": { "title": "Ad status", "enum": [ "ACTIVE", "INACTIVE", "ALL" ], "type": "string", "description": "Whether to return currently running ads, stopped ads, or both. 'ACTIVE' returns live ads only (default), 'INACTIVE' returns stopped ads, 'ALL' returns both. Active-only is the most useful for competitor monitoring.", "default": "ACTIVE" }, "mediaType": { "title": "Media type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "IMAGE_AND_MEME" ], "type": "string", "description": "Filter ads by creative format. 'ALL' returns every format (default), 'IMAGE' returns image ads, 'VIDEO' returns video ads, 'MEME' returns image-with-text. Use this to study a specific creative style for a hashtag.", "default": "ALL" }, "searchType": { "title": "Match type", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "How the hashtag is matched. 'keyword_unordered' matches the tag anywhere in the ad (default, broader recall), 'keyword_exact_phrase' matches the exact phrase only (higher precision). Use exact phrase when a hashtag is a common substring of other words.", "default": "keyword_unordered" }, "sortBy": { "title": "Sort by", "enum": [ "total_impressions", "relevancy_monthly_grouped" ], "type": "string", "description": "Result ordering. 'total_impressions' surfaces the highest-reach ads first (default), 'relevancy_monthly_grouped' uses Meta's relevance grouping. Impressions-first is best for finding the biggest spenders on a hashtag.", "default": "total_impressions" }, "startDate": { "title": "Impressions start date", "type": "string", "description": "Only return ads that were shown on or after this date, in YYYY-MM-DD format (e.g. '2026-01-01'). Leave empty for no lower bound. Use with End date to scope a campaign window." }, "endDate": { "title": "Impressions end date", "type": "string", "description": "Only return ads that were shown on or before this date, in YYYY-MM-DD format (e.g. '2026-03-31'). Leave empty for no upper bound. Combine with Start date to isolate a specific period." }, "includeRaw": { "title": "Include raw provider payload", "type": "boolean", "description": "Set to true to attach the unmodified provider response for each ad under a 'raw' field. Useful for debugging or accessing fields not in the normalized schema. Defaults to false to keep records small and cheap to read.", "default": false }, "providerOrder": { "title": "Provider order", "enum": [ "auto", "scrapecreators-first", "sociavault-first" ], "type": "string", "description": "Internal data-provider order for testing and fallback control. 'auto' tries ScrapeCreators before SociaVault when both secrets exist (default). 'scrapecreators-first' or 'sociavault-first' force an order. Not relevant to most users.", "default": "auto" } } }, "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 } } } } } } } } } }