{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Search Posts Scraper - Keyword, Date & Location",
    "description": "Search public Facebook posts by keyword and get one row per post: text, author Page or profile, date, reactions by type, comments, shares, video views, photos, video and link attachments, group and place. Recent-first, date and location filters, monitor mode. No login or cookies.",
    "version": "0.1",
    "x-build-id": "maGq3edxVvUAQI7Ux"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/topapi~facebook-search-posts-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-topapi-facebook-search-posts-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/topapi~facebook-search-posts-scraper/runs": {
      "post": {
        "operationId": "runs-sync-topapi-facebook-search-posts-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/topapi~facebook-search-posts-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-topapi-facebook-search-posts-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": {
          "searchQueries": {
            "title": "🔎 Search queries",
            "type": "array",
            "description": "Keywords, phrases or hashtags, one per line, e.g. \"coffee\", \"#blackfriday\", \"iPhone 17 battery\". A Facebook search URL such as https://www.facebook.com/search/posts/?q=coffee also works. Facebook's search is fuzzy: it ranks related posts, so turn on 'Only posts that contain the query' for strict results.",
            "items": {
              "type": "string"
            }
          },
          "sortBy": {
            "title": "🔀 Sort by",
            "enum": [
              "top",
              "recent"
            ],
            "type": "string",
            "description": "\"Top\" is Facebook's default ranking (popular posts, any age). \"Most recent first\" returns the newest public posts and pairs with monitor mode for a feed of new mentions.",
            "default": "top"
          },
          "startDate": {
            "title": "📅 Posted after",
            "type": "string",
            "description": "Absolute date (2026-09-01) or relative to now (7 days, 3 weeks, 2 months, 1 year) or a day count (1 = today, 2 = yesterday and today). Sent to Facebook as its date filter and re-checked on every post. Leave empty for no lower bound."
          },
          "endDate": {
            "title": "📅 Posted before",
            "type": "string",
            "description": "Absolute date or relative (e.g. 30 days). A date includes that whole day. Combine with 'Posted after' for a window such as startDate 2026-01-01 + endDate 2026-06-30, or the same date in both for a single day."
          },
          "locationUid": {
            "title": "📍 Location (Facebook place id)",
            "type": "string",
            "description": "Facebook's numeric id of a city or region to restrict the search to posts tagged there, e.g. 108424279189115 (New York, NY). Find it on facebook.com: search, open the city filter and copy the number at the end of the location page URL. Leave empty for a global search."
          },
          "mustContainQuery": {
            "title": "🎯 Only posts that contain the query",
            "type": "boolean",
            "description": "Keep only posts whose text contains the search query (case-insensitive). Facebook's search also returns related posts without the exact words; this makes the result strict. Measured on 307 posts: single words matched 94% (coffee, pizza), multi-word phrases far less (\"hiring now apply\" 0%, \"zillow listing\" 40%).",
            "default": false
          },
          "keywordFilter": {
            "title": "🔤 Keyword filter",
            "type": "string",
            "description": "Keep only posts whose text, author name or link title contain this word or phrase, case-insensitive, e.g. \"recipe\" or \"discount, sale, promo\" (comma = any of them). Leave empty for no filter.",
            "default": ""
          },
          "postType": {
            "title": "🎞️ Post type",
            "enum": [
              "all",
              "photo",
              "video",
              "link",
              "text"
            ],
            "type": "string",
            "description": "Keep only one kind of post. Marketplace listings and event posts count as 'photo' when they carry an image.",
            "default": "all"
          },
          "postSource": {
            "title": "👥 Posted in",
            "enum": [
              "all",
              "groups",
              "pages_and_profiles",
              "business_pages"
            ],
            "type": "string",
            "description": "Where the post was published. Measured on 307 search results: 25% were public-group posts, 4% came from business Pages, the rest from profiles and creator pages.",
            "default": "all"
          },
          "minReactions": {
            "title": "👍 Minimum reactions",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Keep only posts with at least this many reactions, e.g. 100 to keep popular posts only. 0 = no minimum.",
            "default": 0
          },
          "includePostDetails": {
            "title": "💬 Include post details (top comments, video files)",
            "type": "boolean",
            "description": "Opens each post's public page and adds the top comments Facebook shows signed-out (up to about 10: text, author, date, reactions), the video SD/HD file URLs and the video view count. Charged as the post-details event only for posts that received details. About one extra request (0.8 MB) per post.",
            "default": false
          },
          "monitorMode": {
            "title": "🔁 Only new posts since the last run",
            "type": "boolean",
            "description": "Remembers, per search query, which posts were already delivered (in the named key-value store below) and returns only new ones. Works best with 'Most recent first': the run stops as soon as a whole page was already checked, so a scheduled check costs one or two pages. A run that finds nothing new delivers nothing. On schedules faster than hourly, a query is checked on every run while it brings new posts; after two checks in a row with nothing new it is checked every 15 minutes, then every 30, then every hour, until a new post resets it (hourly or slower schedules are checked on every run).",
            "default": false
          },
          "monitorStoreName": {
            "title": "🗄️ Monitor memory name",
            "pattern": "^[a-zA-Z0-9-]{1,63}$",
            "type": "string",
            "description": "Name of the key-value store that keeps the per-query memory for monitor mode. Give each separate feed (a brand, a client, a Slack channel) its own name so they do not hide posts from each other. Letters, digits and hyphens.",
            "default": "facebook-search-posts-monitor"
          },
          "checkEveryQuery": {
            "title": "📡 Read every query on every run (charged per page)",
            "type": "boolean",
            "description": "For long backfills and for monitoring on fast schedules, where every search must be read in full. Switches off the quiet-query pacing and the rule that a run reads further only from what it delivers: every query is read on every run, and each search page read is charged as a 'Search page read' event (Pricing tab) on top of the posts delivered, whether or not its posts fall inside your dates and filters. Off by default, so nothing changes unless you turn it on. Control the cost with 'Max posts per query' or 'Max pages per query per run' (how deep each run reads) and your schedule (how often).",
            "default": false
          },
          "resumeStoreName": {
            "title": "⏯️ Resume memory name (long backfills)",
            "pattern": "^[a-zA-Z0-9-]{0,63}$",
            "type": "string",
            "description": "Leave empty for a normal run. Give a name (letters, digits, hyphens) to let a search continue across runs: each query's position is saved in a key-value store of that name, and the next run with the same queries, sort, dates and filters carries on after the last page it finished. A query Facebook ran out of is not read again. Posts delivered by earlier runs are not delivered or charged twice. Use fixed dates (2026-06-01), not relative ones (7 days), so the window stays the same between runs. Not used in monitor mode."
          },
          "sliceBy": {
            "title": "🗓️ Search the date range by (long backfills)",
            "enum": [
              "none",
              "month",
              "week",
              "day"
            ],
            "type": "string",
            "description": "Facebook serves a limited list of posts per search, so a long date range in one search returns a fraction of it. Pick month, week or day and each query is searched once per window of the range ('Posted after' to 'Posted before'); every row then carries search_window. Needs 'Posted after'; not used in monitor mode. Use with 'Top' (Facebook's recent list starts at today whatever the window) and with a resume memory name, so a long job continues across runs. Each run writes a COVERAGE record: per query and window, finished or not.",
            "default": "none"
          },
          "maxPagesPerSlice": {
            "title": "📄 Max search pages per query (and window) per run",
            "minimum": 0,
            "maximum": 300,
            "type": "integer",
            "description": "Search pages read for one query (one query and window when searching by month/week/day) during one run; a page holds 5-6 posts. With a resume memory name the search continues from there on the next run. 0 = no limit.",
            "default": 0
          },
          "maxPostsPerQuery": {
            "title": "💯 Max posts per query",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Cap per search query after filters (your main cost control; you pay per delivered post). Facebook serves 11-12 posts per page; deep pagination measured to 8+ pages. 0 = as many as Facebook serves, up to 1,000 per query.",
            "default": 50
          },
          "maxItems": {
            "title": "🔢 Max posts in total",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Hard cap for the whole run across all queries. 0 = no total cap (each query is still capped above).",
            "default": 0
          },
          "compact": {
            "title": "🤖 Compact output",
            "type": "boolean",
            "description": "Core fields only (post_id, type, url, message, published_at, author name/url/type, reactions, comments, shares, views, image, video, external_url, group, location, hashtags, search_query): about a fifth of the bytes, sized for AI agents and MCP clients.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "🌍 Proxy",
            "type": "object",
            "description": "Apify datacenter proxies by default. Facebook now answers the search itself only to residential addresses, so the actor opens its session on the datacenter group and moves the search pages to Apify RESIDENTIAL the moment Facebook refuses them (included in the price; no setting needed). Your own proxy URLs, if given, are used for everything.",
            "default": {
              "useApifyProxy": true
            }
          },
          "maxConcurrency": {
            "title": "⚡ Parallel requests",
            "minimum": 1,
            "maximum": 6,
            "type": "integer",
            "description": "Kept for compatibility. The actor reads all queries in parallel on its own (up to 6 at 128 MB, 10 at 256 MB), so this value no longer changes a run.",
            "default": 2
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}