{ "openapi": "3.0.3", "info": { "title": "Facebook Page & Profile Finder by Keyword or URL (server mode)", "version": "1.1", "description": "Send one lookup and get the results back in the response. It takes the same input as a normal run: query parameters with GET, or a JSON body with POST. At most 60 results and 240 seconds per request; start a normal run for bigger jobs. Requests run in your own Apify account at the Actor's normal price.", "x-oa-server-mode": "1.1" }, "paths": { "/": { "get": { "operationId": "lookupGet", "summary": "Run one lookup (query parameters)", "parameters": [ { "name": "mode", "in": "query", "required": true, "description": "Choose whether to discover Pages/profiles by keyword or read the Facebook URLs you already have.", "schema": { "type": "string", "enum": [ "search", "urls" ], "default": "search" }, "example": "search" }, { "name": "searchQueries", "in": "query", "required": false, "description": "Keywords to search on Facebook (mode=search), e.g. 'coffee shop', 'dentist Berlin'. A pasted facebook.com/search/pages/?q=... URL is accepted too. Either this or startUrls is required. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 3 }, "style": "form", "explode": true, "example": [ "Starbucks" ] }, { "name": "searchType", "in": "query", "required": false, "description": "Search for Pages, public profiles, or both. Applies to mode=search.", "schema": { "type": "string", "enum": [ "pages", "people", "all" ], "default": "pages" }, "example": "pages" }, { "name": "location", "in": "query", "required": false, "description": "A city or country added to every keyword, e.g. 'Berlin' or 'Kansas City, Missouri'. Facebook search is relevance-ranked, so this narrows results toward that place; it is not a strict geographic filter.", "schema": { "type": "string" } }, { "name": "locationUids", "in": "query", "required": false, "description": "Optional numeric Facebook Place IDs, one page search per UID, e.g. 108591349161413 from facebook.com/places//. maxResults is distributed across the UIDs and duplicate pages are removed. Results can include nearby businesses; this is not a strict city boundary. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "categoryFilter", "in": "query", "required": false, "description": "Optional case-insensitive text filter on a page's category, e.g. 'dentist' or 'restaurant'. Applied after page details are read; leave empty for all categories.", "schema": { "type": "string" } }, { "name": "startUrls", "in": "query", "required": false, "description": "Direct Facebook Page or profile URLs to read (mode=urls), e.g. https://www.facebook.com/McDonalds, https://www.facebook.com/profile.php?id=..., /people/... or /p/.... Either startUrls, startIds or searchQueries is required. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 5 }, "style": "form", "explode": true }, { "name": "startIds", "in": "query", "required": false, "description": "Numeric Facebook IDs or @handles to read (mode=urls), e.g. 100064458773195 or @McDonalds. Combine with startUrls if you have both. Either startUrls, startIds or searchQueries is required. (GET: repeat the parameter once per value.)", "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 5 }, "style": "form", "explode": true }, { "name": "maxResults", "in": "query", "required": false, "description": "Upper bound on rows per search query (mode=search) or in total (mode=urls). Facebook may return fewer when the index is exhausted. Deep searches use extra networking automatically.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 20 }, "example": 1 }, { "name": "fetchPageDetails", "in": "query", "required": false, "description": "Open each result to add category, contact details, follower counts, ratings and reviews links. Turn off for a fast identity-only list of names, URLs, IDs and verification badges.", "schema": { "type": "boolean", "default": true }, "example": false }, { "name": "includeReviews", "in": "query", "required": false, "description": "Fetch up to 10 real reviews per page when Facebook publishes them. Adds one request per result.", "schema": { "type": "boolean", "default": true }, "example": false }, { "name": "addDetail", "in": "query", "required": false, "description": "Add creation date, whether the Page is currently running ads, and its public Page Transparency ID. Adds one request per result.", "schema": { "type": "boolean", "default": false } }, { "name": "includePosts", "in": "query", "required": false, "description": "Add up to maxPosts recent posts from the Page/profile timeline (text, timestamp, permalink, media and engagement when visible).", "schema": { "type": "boolean", "default": false } }, { "name": "maxPosts", "in": "query", "required": false, "description": "Maximum recent posts to keep per result when includePosts is on. Facebook may serve fewer when the timeline is empty or restricted.", "schema": { "type": "integer", "default": 5, "minimum": 1, "maximum": 10 } }, { "name": "verifiedOnly", "in": "query", "required": false, "description": "Keep only results Facebook marks as verified. Unverified or unknown results are dropped.", "schema": { "type": "boolean", "default": false } }, { "name": "rehostImages", "in": "query", "required": false, "description": "Copy profile and cover images into Apify storage so their URLs stay valid, instead of returning Facebook's signed CDN links (which expire after about five days). Adds one download per image.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "The results as a JSON array (at most 60). They are also saved to the run's dataset and billed per result, like a normal run.", "headers": { "X-Item-Count": { "schema": { "type": "integer" }, "description": "Results returned." }, "X-Status-Message": { "schema": { "type": "string" }, "description": "The Actor's last status message, e.g. why nothing was found." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } }, "400": { "description": "Invalid, missing or unknown input fields. Nothing ran.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_input", "errorDescription": "mode: required" } } } }, "422": { "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The request used up its 240 s budget. The results found so far are in partialItems.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "partialItems": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] } } } } } }, "post": { "operationId": "lookupPost", "summary": "Run one lookup (JSON body)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "urls" ], "default": "search", "description": "Choose whether to discover Pages/profiles by keyword or read the Facebook URLs you already have." }, "searchQueries": { "type": "array", "items": { "type": "string" }, "maxItems": 3, "description": "Keywords to search on Facebook (mode=search), e.g. 'coffee shop', 'dentist Berlin'. A pasted facebook.com/search/pages/?q=... URL is accepted too. Either this or startUrls is required." }, "searchType": { "type": "string", "enum": [ "pages", "people", "all" ], "default": "pages", "description": "Search for Pages, public profiles, or both. Applies to mode=search." }, "location": { "type": "string", "description": "A city or country added to every keyword, e.g. 'Berlin' or 'Kansas City, Missouri'. Facebook search is relevance-ranked, so this narrows results toward that place; it is not a strict geographic filter." }, "locationUids": { "type": "array", "items": { "type": "string" }, "description": "Optional numeric Facebook Place IDs, one page search per UID, e.g. 108591349161413 from facebook.com/places//. maxResults is distributed across the UIDs and duplicate pages are removed. Results can include nearby businesses; this is not a strict city boundary." }, "categoryFilter": { "type": "string", "description": "Optional case-insensitive text filter on a page's category, e.g. 'dentist' or 'restaurant'. Applied after page details are read; leave empty for all categories." }, "startUrls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, "maxItems": 5, "description": "Direct Facebook Page or profile URLs to read (mode=urls), e.g. https://www.facebook.com/McDonalds, https://www.facebook.com/profile.php?id=..., /people/... or /p/.... Either startUrls, startIds or searchQueries is required." }, "startIds": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "Numeric Facebook IDs or @handles to read (mode=urls), e.g. 100064458773195 or @McDonalds. Combine with startUrls if you have both. Either startUrls, startIds or searchQueries is required." }, "maxResults": { "type": "integer", "default": 20, "minimum": 1, "maximum": 20, "description": "Upper bound on rows per search query (mode=search) or in total (mode=urls). Facebook may return fewer when the index is exhausted. Deep searches use extra networking automatically." }, "fetchPageDetails": { "type": "boolean", "default": true, "description": "Open each result to add category, contact details, follower counts, ratings and reviews links. Turn off for a fast identity-only list of names, URLs, IDs and verification badges." }, "includeReviews": { "type": "boolean", "default": true, "description": "Fetch up to 10 real reviews per page when Facebook publishes them. Adds one request per result." }, "addDetail": { "type": "boolean", "default": false, "description": "Add creation date, whether the Page is currently running ads, and its public Page Transparency ID. Adds one request per result." }, "includePosts": { "type": "boolean", "default": false, "description": "Add up to maxPosts recent posts from the Page/profile timeline (text, timestamp, permalink, media and engagement when visible)." }, "maxPosts": { "type": "integer", "default": 5, "minimum": 1, "maximum": 10, "description": "Maximum recent posts to keep per result when includePosts is on. Facebook may serve fewer when the timeline is empty or restricted." }, "verifiedOnly": { "type": "boolean", "default": false, "description": "Keep only results Facebook marks as verified. Unverified or unknown results are dropped." }, "rehostImages": { "type": "boolean", "default": false, "description": "Copy profile and cover images into Apify storage so their URLs stay valid, instead of returning Facebook's signed CDN links (which expire after about five days). Adds one download per image." } }, "additionalProperties": false, "required": [ "mode" ] }, "example": { "mode": "search", "searchQueries": [ "Starbucks" ], "searchType": "pages", "maxResults": 1, "fetchPageDetails": false, "includeReviews": false } } } }, "responses": { "200": { "description": "The results as a JSON array (at most 60). They are also saved to the run's dataset and billed per result, like a normal run.", "headers": { "X-Item-Count": { "schema": { "type": "integer" }, "description": "Results returned." }, "X-Status-Message": { "schema": { "type": "string" }, "description": "The Actor's last status message, e.g. why nothing was found." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } }, "400": { "description": "Invalid, missing or unknown input fields. Nothing ran.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_input", "errorDescription": "mode: required" } } } }, "422": { "description": "The Actor could not complete this request (for example, nothing matches). No results were delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure. Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The request used up its 240 s budget. The results found so far are in partialItems.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "partialItems": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } } } ] } } } } } } } }, "components": { "schemas": { "Item": { "type": "object", "description": "One result, the same record a normal run saves to its dataset.", "properties": { "pageName": {}, "facebookUrl": {}, "entityType": {}, "verified": {}, "category": {}, "likes": {}, "followers": {}, "phone": {}, "recommendPercentage": {}, "searchQuery": {} } }, "Error": { "type": "object", "required": [ "error", "errorDescription" ], "properties": { "error": { "type": "string", "enum": [ "invalid_input", "request_failed", "internal_error", "timeout", "busy", "not_found", "method_not_allowed", "payload_too_large" ] }, "errorDescription": { "type": "string" } } } }, "securitySchemes": { "apifyToken": { "type": "http", "scheme": "bearer", "description": "Your Apify API token (Apify Console, Settings, API and integrations)." } } }, "servers": [ { "url": "https://cjq13rwjckkpe9rcc.apify.actor" } ], "security": [ { "apifyToken": [] } ] }