{
  "openapi": "3.0.1",
  "info": {
    "title": "All-in-One Facebook Scraper",
    "description": "Facebook scraper — 12 modes: pages, posts, events, groups, search, reviews, comments, marketplace, reels & ads. HTTP-only, 256MB, fast. Premium residential proxy (~95% success rate). Up to 50% cheaper than alternatives. MCP-ready for AI agents.",
    "version": "0.1",
    "x-build-id": "0T8Vdlnv6m6efvAP2"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/get-leads~all-in-one-facebook-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-get-leads-all-in-one-facebook-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/get-leads~all-in-one-facebook-scraper/runs": {
      "post": {
        "operationId": "runs-sync-get-leads-all-in-one-facebook-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/get-leads~all-in-one-facebook-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-get-leads-all-in-one-facebook-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": [
          "scrapeMode"
        ],
        "properties": {
          "scrapeMode": {
            "title": "Scrape Mode",
            "enum": [
              "facebook-scraper",
              "facebook-pages-scraper",
              "facebook-posts-scraper",
              "facebook-events-scraper",
              "facebook-groups-scraper",
              "facebook-search-scraper",
              "facebook-reviews-scraper",
              "facebook-comments-scraper",
              "facebook-marketplace-scraper",
              "facebook-reels-scraper",
              "facebook-ads-scraper",
              "facebook-data-extractor",
              "facebook-monitor",
              "facebook-validator"
            ],
            "type": "string",
            "description": "Choose what to scrape from Facebook.",
            "default": "facebook-pages-scraper"
          },
          "pages": {
            "title": "Facebook Pages",
            "type": "array",
            "description": "Facebook page names or URLs to scrape. Used by pages, posts, and events modes. Example: NASA, https://facebook.com/cern",
            "items": {
              "type": "string"
            }
          },
          "eventSearchQueries": {
            "title": "Event Search Queries",
            "type": "array",
            "description": "Search terms for finding Facebook events. Used by events mode. Example: music festival, tech conference",
            "items": {
              "type": "string"
            }
          },
          "groupUrls": {
            "title": "Facebook Group URLs",
            "type": "array",
            "description": "Facebook group URLs or names. **Public groups: cookieless** — no loginCookies needed; the scraper extracts an fb_dtsg token from the public group HTML and paginates via FB's GraphQL API (mirrors the swerve/fb-group-scraper technique). **Private/closed groups: cookies required** — paste loginCookies and the authenticated account must be a member. Example: https://facebook.com/groups/selftaughtprogrammers (public). The scraper auto-selects: cookieless when loginCookies is empty, cookied when loginCookies is provided.",
            "items": {
              "type": "string"
            }
          },
          "searchQueries": {
            "title": "Search Queries",
            "type": "array",
            "description": "Keywords to search Facebook pages. Requires loginCookies. Example: coffee shop new york, web design agency london",
            "items": {
              "type": "string"
            }
          },
          "marketplaceQueries": {
            "title": "Marketplace Search Queries",
            "type": "array",
            "description": "Search terms for Facebook Marketplace listings. Example: guitar, laptop, apartment. Requires loginCookies — Facebook redirects unauthenticated Marketplace requests to the login page.",
            "items": {
              "type": "string"
            }
          },
          "marketplaceLocation": {
            "title": "Marketplace Location",
            "type": "string",
            "description": "Location for marketplace search. Example: sanfrancisco, newyork, london"
          },
          "adsQuery": {
            "title": "Ads Search Query",
            "type": "string",
            "description": "Search term for Meta Ad Library. Example: nike, coffee, web design. Searches across all ad creatives and page names."
          },
          "adsPageId": {
            "title": "Ads Page ID",
            "type": "string",
            "description": "Facebook Page ID to scrape ads from a specific page. Find it in the page's About section or URL. Example: 14226545351 (Red Bull)"
          },
          "adsCountry": {
            "title": "Ads Country",
            "type": "string",
            "description": "Country code for Ad Library search. Use 'ALL' for all countries. Example: US, GB, DE, FR",
            "default": "ALL"
          },
          "adsActiveStatus": {
            "title": "Ads Active Status",
            "enum": [
              "active",
              "inactive",
              "all"
            ],
            "type": "string",
            "description": "Filter ads by status.",
            "default": "active"
          },
          "onlyPostsNewerThan": {
            "title": "Only Posts Newer Than",
            "type": "string",
            "description": "Filter results by date. Supports ISO dates (2026-01-01), relative values (7 days, 2 months, 1 year), or Unix timestamps. Works with Posts mode (login cookies), Groups mode (publishTime), and Comments mode (createdTime)."
          },
          "onlyPostsOlderThan": {
            "title": "Only Posts Older Than",
            "type": "string",
            "description": "Filter results by date. Same format as onlyPostsNewerThan. Works with Posts, Groups, and Comments modes."
          },
          "resultsPerPage": {
            "title": "Max Results Per Input",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Maximum number of results to extract per page, group, or search query.",
            "default": 50
          },
          "enrichCommentLikes": {
            "title": "Enrich Comments with likesCount (slower, +bandwidth)",
            "type": "boolean",
            "description": "Comments mode: when enabled, the scraper fetches each comment's parent-post permalink (~1.2 MB/post) to extract per-comment likesCount. likesCount is server-rendered only on the permalink view, not in the feed response. Default OFF for cost — likesCount is data-absent for ~50% of feed comments anyway (Facebook only exposes reaction counts on the permalink's top-N visible comments). Enable ONLY if your downstream depends on per-comment likes for sorting or analytics.",
            "default": false
          },
          "loginCookies": {
            "title": "Login Cookies 🍪 Bring Your Own — required for authenticated modes",
            "type": "string",
            "description": "🍪 **You must provide your OWN Facebook cookies.** This actor does NOT include any cookies for customer runs (privacy + Facebook ToS — the actor cannot run as someone else's identity). One set per line: c_user=XXX; xs=XXX. Multiple cookie sets rotate automatically on session blocks. **REQUIRED** for search, reviews, comments, reels, ads (run errors out for these modes if loginCookies is empty). **Optional for groups** — public groups now run cookieless via FB GraphQL with fb_dtsg from the public page; loginCookies is only needed for private/closed groups. Strongly **recommended** for posts and marketplace. **NOT used** for pages and events modes (those work fully cookieless). 2026-05-06 enhancement: pages and posts modes try cookieless first and fall back to your cookies only if FB serves a login-wall — your account is exposed less. How to get: open facebook.com in Chrome while logged in → F12 → Application → Cookies → https://www.facebook.com → copy the `c_user` and `xs` values. If FB rejects the cookies mid-run with \"session expired (error 1357001)\", repaste fresh values — the `xs` token rotates every few hours of active use."
          },
          "requestDelay": {
            "title": "Request Delay (ms)",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Delay between requests in milliseconds. Use 0 to keep the built-in human-like delays (recommended), or 3000+ for extra stealth on sensitive workloads.",
            "default": 0
          },
          "safetyProfile": {
            "title": "Safety profile (anti-detection tuning)",
            "enum": [
              "aggressive",
              "balanced",
              "safe",
              "first-scrape"
            ],
            "type": "string",
            "description": "Preset bundle of delays + session rotation + warmup curve tuned for different risk postures. 'balanced' (default) matches normal human browsing cadence. 'safe' is slower and more cautious — use for recently-warned accounts. 'first-scrape' is ultra-slow onboarding — use for a brand-new cookie/IP pair or immediately after a suspension. 'aggressive' is the legacy high-throughput mode — only use on research accounts you can afford to lose.",
            "default": "balanced"
          },
          "maxDailyRequestsPerCookie": {
            "title": "Daily request ceiling per cookie (safety)",
            "minimum": 50,
            "maximum": 50000,
            "type": "integer",
            "description": "Hard daily ceiling on how many HTTP requests a single cookie (by c_user ID) can drive through this actor within a 24h UTC window. When a run's estimated request footprint would push the cookie past this ceiling, the run aborts with Actor.fail BEFORE any scraping begins. Prevents a misconfigured cron/test runner from burning through the account. Recommended: 500 for a research account, 200 for your main account, leave blank to disable."
          },
          "maxHourlyRequestsPerCookie": {
            "title": "Hourly request ceiling per cookie (burst safety)",
            "minimum": 20,
            "maximum": 5000,
            "type": "integer",
            "description": "Burst-protection ceiling that complements the daily one. A run firing 500 requests in 10 min can pass the daily check but still looks like a crawler to Meta. The hourly counter (keyed by c_user + UTC hour) forces natural spacing across any single clock hour. Recommended: 100 for most workloads, 50 for stealth. Leave blank to disable."
          },
          "validatorTargets": {
            "title": "Validator Targets (facebook-validator mode)",
            "type": "array",
            "description": "Array of { url, expected } objects used by facebook-validator mode to regression-test parser output against known ground-truth values. For each target the scraper fetches the URL, parses it with the appropriate parser, and emits a diff showing which expected fields matched (PASS), partially matched (PARTIAL), or drifted (FAIL). Example: [{\"url\":\"https://www.facebook.com/NASA\",\"expected\":{\"likesCount\":28650100,\"isVerified\":true}}]. String comparison is case-insensitive substring match; number comparison tolerates ±2% drift (FB counts round between visits); booleans must be strictly equal."
          },
          "skipCookieHealthCheck": {
            "title": "Skip cookie preflight (debugging)",
            "type": "boolean",
            "description": "When true, skip the /me cookie health check that runs before scraping. Normally the preflight catches expired cookies up-front and aborts the run to avoid feeding Meta's abuse score. Only skip this if you are debugging the preflight itself.",
            "default": false
          },
          "proxyTier": {
            "title": "Proxy Tier",
            "enum": [
              "none",
              "residential",
              "custom"
            ],
            "type": "string",
            "description": "Choose your proxy setup. 'Residential (built-in)' is the default — routes all modes through an included residential proxy and unlocks high-traffic brand pages (Apple, Google, SpaceX, Amazon, Microsoft) that block datacenter IPs. 'None' skips proxy entirely (works for most public pages but may hit CAPTCHAs on brand pages). 'Bring your own' uses the proxy URL you paste into customProxyUrl below. Apify Residential Proxy is NOT supported by this actor.",
            "default": "residential"
          },
          "customProxyUrl": {
            "title": "Custom Proxy URL (bring your own)",
            "type": "string",
            "description": "Required when proxyTier=custom. Paste one residential proxy URL in the format http://user:pass@host:port. Works with any residential-proxy provider that gives you a plain URL (Evomi, DataImpulse, Oxylabs, Smartproxy, etc.). Apify Residential Proxy is not supported by this actor — its pricing makes the actor's unit economics impossible, so we removed the old Apify-proxy editor entirely. For brand pages (Apple, Google, SpaceX, Amazon, Microsoft), also set forceProxy=true so the custom proxy is applied to every mode, not just GraphQL-heavy ones."
          },
          "forceProxy": {
            "title": "Force Proxy on All Modes",
            "type": "boolean",
            "description": "Apply the configured proxy (customProxyUrl above) to ALL modes including public ones (pages, posts, events). Required when using a custom residential proxy for brand pages. Not needed when proxyTier=residential — that already forces proxy on all modes.",
            "default": false
          },
          "facebookAppToken": {
            "title": "Facebook App Access Token (Ads API)",
            "type": "string",
            "description": "Optional Facebook App access token for the Ad Library Graph API. Enables Ads mode without login cookies. Format: {app_id}|{app_secret} or a User Access Token. Get one at developers.facebook.com/tools/explorer/ — select your app and generate a token with ads_read permission. When provided, takes priority over loginCookies for ads scraping and returns richer structured data (impressions range, spend range, targeting info)."
          },
          "alertEmail": {
            "title": "Alert email (monitor mode)",
            "type": "string",
            "description": "Email to send health-check alerts to. Used by facebook-monitor mode.",
            "default": ""
          },
          "apifyToken": {
            "title": "Apify API token (monitor mode)",
            "type": "string",
            "description": "Personal API token for monitor mode (needed to read run history + send emails)."
          },
          "forceAdmissionDeny": {
            "title": "[TEST-ONLY] Force admission gate denial",
            "type": "boolean",
            "description": "Plan v3 Layer 3 / Build 0.1.215+. When true, the admission gate (src/lib/admission-gate.js) simulates a denial regardless of actual KV state. In hard mode this fails the run with a synthetic-test-deny reason; in soft mode it logs the would-block but proceeds. Used to validate Layer 3 wiring without filling the cookie pool. NEVER set true in production — synthetic events are tagged `_synthetic: true` so analyzer can filter them.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}