{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Posts Backfill Scraper - Keyword History by Date",
    "description": "Collect the public Facebook posts for your keywords over a past date range. The range is searched month by month, week by week or day by day, every search is read to its end, runs continue where the last one stopped, and a coverage report shows which windows are finished. No login or cookies.",
    "version": "0.1",
    "x-build-id": "cx5APY8RW1Ha1HJT6"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/topapi~facebook-posts-backfill-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-topapi-facebook-posts-backfill-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-posts-backfill-scraper/runs": {
      "post": {
        "operationId": "runs-sync-topapi-facebook-posts-backfill-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-posts-backfill-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-topapi-facebook-posts-backfill-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": "🔎 Keywords",
            "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. Each keyword is searched once per date window; every row carries search_query and search_window.",
            "items": {
              "type": "string"
            }
          },
          "startDate": {
            "title": "📅 From",
            "type": "string",
            "description": "Start of the range. Use a fixed date (2025-10-01) for a job you will continue over several runs: the windows stay the same and the job memory is on. Relative values (3 months, 1 year) also work, as a one-off run. Empty = the last 30 days."
          },
          "endDate": {
            "title": "📅 To",
            "type": "string",
            "description": "End of the range; a date includes that whole day (2026-09-30). Empty = today."
          },
          "sliceBy": {
            "title": "🗓️ Search the range by",
            "enum": [
              "month",
              "week",
              "day",
              "none"
            ],
            "type": "string",
            "description": "Facebook serves a limited list of posts per search, so a long range is searched one window at a time. Smaller windows find more posts and read more pages: a year by month is 12 searches per keyword, by week 53. Keep the same choice between runs of one job.",
            "default": "month"
          },
          "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
          },
          "maxPagesPerSlice": {
            "title": "📄 Max pages per keyword and window, per run",
            "minimum": 0,
            "maximum": 300,
            "type": "integer",
            "description": "Search pages read for one keyword in one date window during one run (a page holds 5-6 posts). A search that stops here keeps its position and continues on the next run. 0 = read until Facebook has no more.",
            "default": 0
          },
          "maxPostsPerSlice": {
            "title": "💯 Max posts per keyword and window",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Posts delivered for one keyword in one date window. 0 = as many as Facebook serves, up to 1,000.",
            "default": 0
          },
          "maxItems": {
            "title": "🔢 Max posts in total",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Hard cap for the whole run across all keywords and windows. 0 = no total cap.",
            "default": 0
          },
          "resumeStoreName": {
            "title": "⏯️ Job memory name",
            "pattern": "^[a-zA-Z0-9-]{0,63}$",
            "type": "string",
            "description": "Name of the key-value store that keeps each keyword and window's position, the posts already delivered and the coverage report. A search Facebook ran out of is not read again, and a post delivered by an earlier run is not delivered or charged twice. Give each separate job its own name (letters, digits, hyphens). With the default name the memory is used only when 'From' is a fixed date (2025-10-01); a run with a relative start (2 months) is a one-off unless you set a name of your own. Empty = no memory.",
            "default": "facebook-posts-backfill"
          },
          "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
          },
          "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 proxies by default: the session opens on the datacenter group and the search pages are read through Apify RESIDENTIAL (included in the price; no setting needed). Your own proxy URLs, if given, are used for everything.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}