{ "openapi": "3.0.1", "info": { "title": "Facebook Post Search & Keyword Scraper API", "description": "Search public Facebook posts by keyword, phrase, or hashtag. Export globally deduplicated posts with text, authors, dates, engagement, media, and match evidence. Use multiple queries in one run, verify literal matches, and distinguish confirmed no-results from blocked or partial searches.", "version": "0.0", "x-build-id": "mWcNF09rT2IQagryK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/overbifrost~facebook-post-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-overbifrost-facebook-post-search-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/overbifrost~facebook-post-search-scraper/runs": { "post": { "operationId": "runs-sync-overbifrost-facebook-post-search-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/overbifrost~facebook-post-search-scraper/run-sync": { "post": { "operationId": "run-sync-overbifrost-facebook-post-search-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": [ "queries" ], "properties": { "queries": { "title": "Keywords or Facebook links", "minItems": 1, "maxItems": 100, "type": "array", "description": "Add one keyword, hashtag, unfiltered Facebook posts-search link or individual post link per item. Search links reuse their text through Google’s index; direct post links are fetched directly.", "items": { "type": "string", "maxLength": 300 } }, "maxPostsPerQuery": { "title": "Posts per search", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum posts saved per search after matching and filters. Fewer may be available. Increase the scan limit under Search depth if filtering or monitoring skips too many candidates.", "default": 20 }, "maxUniquePosts": { "title": "Total post limit", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Maximum unique posts saved across all inputs. A post found by several searches counts once. Increase both result limits for more posts from one search.", "default": 500 }, "hashtags": { "title": "Extra hashtags", "maxItems": 100, "type": "array", "description": "Optional additional hashtag searches, with or without #. Together with keywords, at most 100 search inputs.", "items": { "type": "string", "maxLength": 101 } }, "dateFrom": { "title": "Published from", "type": "string", "description": "Keep observed publication dates on or after this value. Use a date, ISO timestamp or relative value such as 7 days. Relative dates resolve once at run start; checks use UTC and do not expand search coverage." }, "dateTo": { "title": "Published to", "type": "string", "description": "Keep observed publication dates on or before this value. A date-only value includes the whole UTC day. Accepts ISO timestamps and relative values such as 1 day. Leave empty for no upper bound." }, "unknownDate": { "title": "Posts without a publication date", "enum": [ "KEEP_FLAGGED", "DROP" ], "type": "string", "description": "Choose what happens when a post's publication date is unavailable. Keeping it can include posts outside your date range. Used only when a date filter is set.", "default": "KEEP_FLAGGED" }, "matchMode": { "title": "Keyword matching", "enum": [ "SOURCE_RESULT", "CONTAINS", "EXACT_PHRASE", "WHOLE_WORD", "HASHTAG", "ALL_TERMS", "ANY_TERM" ], "type": "string", "description": "Related results keep Google-ranked discoveries. Stricter modes require collected post text to match. All terms / Any term support quoted phrases, OR alternatives and -exclusions. Direct post links need no keyword match.", "default": "SOURCE_RESULT" }, "filters": { "title": "Post filters", "type": "object", "description": "Optional checks on observed post data. Empty selections keep all types; positive minimums require an observed count. Unknown language or tagged place does not pass those filters.", "properties": { "sourceTypes": { "title": "Post source", "type": "array", "description": "Keep posts from the selected source types. Leave empty for all sources; a source may remain unknown when Facebook does not identify it.", "editor": "select", "items": { "type": "string", "enum": [ "PAGE", "GROUP", "PROFILE", "EVENT", "UNKNOWN" ], "enumTitles": [ "Pages", "Groups", "Profiles", "Events", "Unknown" ] }, "uniqueItems": true }, "postTypes": { "title": "Post types", "type": "array", "description": "Keep the selected types. Select both Video and Reel to include both video formats. Leave empty for all types.", "editor": "select", "items": { "type": "string", "enum": [ "TEXT", "LINK", "PHOTO", "ALBUM", "VIDEO", "REEL", "SHARE", "UNKNOWN" ], "enumTitles": [ "Text", "Link", "Photo", "Photo albums", "Video", "Reel", "Shared post", "Unknown" ] }, "uniqueItems": true }, "minReactions": { "title": "Minimum reactions", "type": "integer", "description": "Leave empty for any count. Keep posts with at least this many reactions; an unavailable count does not meet a positive minimum.", "minimum": 0, "editor": "number" }, "minComments": { "title": "Minimum comments", "type": "integer", "description": "Leave empty for any count. Keep posts with at least this many comments; an unavailable count does not meet a positive minimum.", "minimum": 0, "editor": "number" }, "minShares": { "title": "Minimum shares", "type": "integer", "description": "Leave empty for any count. Keep posts with at least this many shares; an unavailable count does not meet a positive minimum.", "minimum": 0, "editor": "number" }, "mediaOnly": { "title": "Media only", "type": "boolean", "description": "Only posts with at least one media attachment.", "default": false, "editor": "hidden" }, "videoOnly": { "title": "Video only", "type": "boolean", "description": "Only keep posts detected as VIDEO or REEL. Applied locally after acquisition.", "default": false, "editor": "hidden" }, "linkOnly": { "title": "Link only", "type": "boolean", "description": "Only keep posts that link externally — detected LINK type, a link attachment, or an external URL in the text. Applied locally after acquisition.", "default": false, "editor": "hidden" }, "languages": { "title": "Post languages", "type": "array", "description": "Optional two-letter language codes such as en or es. Uses statistical detection from post text; short or ambiguous text stays unknown and is excluded by this filter.", "editor": "stringList", "maxItems": 82, "items": { "type": "string", "pattern": "^[a-z]{2}$" } }, "authorTypes": { "title": "Author types", "type": "array", "description": "Keep selected author types using only source-provided identity. Business-page status is not inferred from a name.", "editor": "select", "items": { "type": "string", "enum": [ "PAGE", "PROFILE", "UNKNOWN" ], "enumTitles": [ "Pages", "Profiles", "Unknown" ] }, "uniqueItems": true }, "excludeReshares": { "title": "Exclude observed reshares", "type": "boolean", "description": "Exclude posts that explicitly share another Facebook post. Unknown share status is retained with a note.", "default": false }, "taggedLocationIds": { "title": "Tagged place IDs", "type": "array", "description": "Optional exact Facebook place IDs explicitly tagged on a collected post. Checked locally; does not perform native location search, infer an author address or expand discovery. Unknown tagged places are excluded.", "editor": "stringList", "maxItems": 100, "items": { "type": "string", "pattern": "^\\d{1,40}$" } } } }, "includeTopComments": { "title": "Include visible top comments", "type": "boolean", "description": "Collect up to the selected number of top-level comments already exposed in the public post document. Does not fetch a complete thread or make additional comment requests.", "default": false }, "maxTopCommentsPerPost": { "title": "Top comments per post", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum visible top-level comments per post when enabled. Fewer or no comments may be exposed. Default 10." }, "outputFormat": { "title": "Dataset format", "enum": [ "FULL", "FLAT" ], "type": "string", "description": "Full keeps nested post data. Flat uses scalar spreadsheet columns and preserves nested details in JSON text cells; use the Flat dataset view. HTML results keep the same readable format." }, "writeCsv": { "title": "Also save posts.csv", "type": "boolean", "description": "Write a UTF-8 CSV file in the run storage. Safe for spreadsheet formulas, with a 32 MiB artifact bound. The summary reports any truncation; the Dataset retains the saved post rows.", "default": false }, "onlyNewPosts": { "title": "Only posts not returned before", "type": "boolean", "description": "Remember saved posts for this search configuration across runs. Previously saved posts are skipped without a post charge. Uses bounded persistent history; does not discover posts missing from the search index.", "default": false }, "monitorName": { "title": "Monitoring profile", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$", "type": "string", "description": "Keep the same profile for repeated runs. Choose another name for independent monitoring history. The default profile is default." }, "monitorRetentionDays": { "title": "Remember posts for days", "minimum": 1, "maximum": 365, "type": "integer", "description": "History retention when monitoring is enabled. Default 90 days. History also has a fixed capacity of 51,200 search/identity hashes; expired or evicted posts can appear again." }, "previousDatasetId": { "title": "Previous results", "maxLength": 64, "type": "string", "description": "Choose a previous Dataset to skip posts it already contains. That Dataset is read only. The previous run is not selected automatically." }, "excludePostIds": { "title": "Exclude post IDs or links", "maxItems": 5000, "type": "array", "description": "Skip specific posts by adding their Facebook post IDs or post links, one per item.", "items": { "type": "string", "maxLength": 200 } }, "maxScannedPostsPerQuery": { "title": "Post scan limit per search", "minimum": 1, "maximum": 500, "type": "integer", "description": "Optional wider scan window when filters or monitoring discard posts. By default it equals Posts per search. Saved posts still respect the result limits. Document, request, byte and time bounds also apply." }, "maxConcurrency": { "title": "Parallel searches", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of searches acquired in parallel, from 1 to 10. Higher values may finish multi-query runs sooner but consume the shared work budget faster. The small prefilled run uses 1; API default is 3.", "default": 3 }, "minDelayMs": { "title": "Minimum post request interval (ms)", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Minimum time between starting Facebook post-document requests, shared across searches. Default 0 ms. Maximum defaults to the same value. Cached documents add no wait." }, "maxDelayMs": { "title": "Maximum post request interval (ms)", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Upper end of the interval between Facebook post-document request starts. Must be at least the minimum; at most 10,000 ms. Leave empty to use the minimum." }, "maxSerpPagesPerQuery": { "title": "Max index pages per query", "minimum": 1, "maximum": 10, "type": "integer", "description": "Hard bound on Google index result pages fetched per query on the discovery leg. Default 5.", "default": 5 }, "maxDocumentsPerQuery": { "title": "Max Facebook documents per query", "minimum": 1, "maximum": 50, "type": "integer", "description": "Hard bound on public logged-out Facebook document fetches per query. Default 24.", "default": 24 }, "maxTotalRequests": { "title": "Total acquisition attempt limit", "minimum": 1, "maximum": 400, "type": "integer", "description": "Shared run bound for admitted SERP, goto and Facebook document attempts, including failed attempts. A denied request is never sent. Platform usage costs remain separate from delivered-post billing.", "default": 400 }, "maxTotalResponseMiB": { "title": "Decoded response limit (MiB)", "minimum": 1, "maximum": 256, "type": "integer", "description": "Shared decoded response bound. One bounded final response may cross the limit; later requests stop. This measures decoded response bodies, not billed transfer bytes or dollars.", "default": 256 }, "proxyStrategy": { "title": "Proxy strategy (Facebook document leg)", "pattern": "^(?:AUTO|NONE|APIFY_DATACENTER|APIFY_RESIDENTIAL)(?![\\s\\S])", "type": "string", "description": "JSON/API only: AUTO uses Apify datacenter for Facebook documents. Other values: NONE, APIFY_DATACENTER, APIFY_RESIDENTIAL. Residential traffic is explicit opt-in.", "default": "AUTO" }, "sortBy": { "title": "Sort order", "pattern": "^(?:TOP|RECENT)(?![\\s\\S])", "type": "string", "description": "JSON/API only: TOP uses Google index relevance. RECENT is accepted for compatibility, falls back to index order and is reported UNSUPPORTED. Newest-first search is not available.", "default": "TOP" }, "discoveryQueryVariant": { "title": "Index query variant", "pattern": "^(?:BROAD_V1|POST_URL_BIASED_V1)(?![\\s\\S])", "type": "string", "description": "JSON/API diagnostic setting: BROAD_V1 is the default; POST_URL_BIASED_V1 restricts individual-post URL families. Normal runs do not need to change this.", "default": "BROAD_V1" }, "discoveryTransportVariant": { "title": "Discovery transport variant", "pattern": "^(?:SERP_RICH_CONTROL|SERP_BASIC_GBV1|DATACENTER_BASIC_GBV1_WITH_SERP_FALLBACK)(?![\\s\\S])", "type": "string", "description": "JSON/API diagnostic setting: SERP_RICH_CONTROL is the default. SERP_BASIC_GBV1 and DATACENTER_BASIC_GBV1_WITH_SERP_FALLBACK are experimental and do not expand Facebook coverage.", "default": "SERP_RICH_CONTROL" }, "optimizationComparison": { "title": "Require unbilled comparison", "type": "boolean", "description": "Adds the comparison summary and refuses PPE billing before acquisition. Use only for an unpublished, unmonetized owner acceptance run; platform compute/proxy costs still apply.", "default": false }, "saveDiscoveryDiagnostics": { "title": "Save discovery failure diagnostics", "type": "boolean", "description": "JSON/API troubleshooting only. When enabled and a query fails or is blocked, save up to four redacted Google response excerpts in DISCOVERY_DEBUG.json (512 KiB total). Removes scripts, form values, opaque links and tracking parameters. Public result text and the supplied search query may remain. No extra HTTP request or post charge. Disabled by default.", "default": 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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }