# Facebook Profile Search API

Search public Facebook profiles by name without a login. Each result has the profile name, the canonical profile URL, the avatar URL and the numeric profile id when Facebook shows it. Facebook serves one list of loose name matches per search, usually about a dozen profiles, and has no next page, so the response says pagination is none and never labels results as another page. The limit parameter only trims that list. Results are de-duplicated by URL. Names are matched loosely, so the profile you want may not be first. To find business pages, use the Facebook Ad Library advertisers endpoint. Costs 1 credit per successful request. A search Facebook could not answer is never billed.

- **Documentation:** [https://scrappa.co/docs/facebook-api/facebook_search_profiles](https://scrappa.co/docs/facebook-api/facebook_search_profiles)
- **API group:** Facebook API
- **Endpoint:** `GET https://scrappa.co/api/facebook/search/profiles`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Person or profile name to search for (1 to 120 characters), e.g. john smith. |
| `limit` | integer | No | Maximum number of profiles to return, 1 to 50. Defaults to 50. One search page holds about a dozen profiles, so a larger limit returns the whole page. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/facebook/search/profiles?query=john+smith&limit=10"
```

## Example response

```json
{
    "success": true,
    "items": [
        {
            "name": "John Smith",
            "url": "https://www.facebook.com/people/John-Smith/pfbid02U5kyzom4RU5bb7JUGgDrsGXaXbDkYCNW6gNjgyG618fu9bF7q9PCqHzHkVRenDJgl/",
            "avatar_url": "https://...",
            "profile_id": "61588140672633"
        }
    ],
    "items_count": 1,
    "search_parameters": {
        "query": "john smith",
        "limit": 10
    },
    "coverage": {
        "pagination": "none",
        "pages_returned": 1,
        "note": "Facebook serves one list of loose name matches per search. There is no next page."
    },
    "meta": {
        "classification": "ok",
        "billable": true,
        "endpoint_family": "facebook_search_profiles",
        "duration_ms": 1300
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required parameter is missing or malformed, for example a handle with characters Facebook does not allow or a non-numeric id. |
| 404 | Not Found | The page, profile, group, event, photo, reel, post or listing does not exist, is not public, or was served by Facebook without the requested record. This is the truthful answer, not a temporary fault: it is never billed and retrying the same permalink will not change it. |
| 503 | Records Not Read | Facebook returned records for this request that the parser could not read. The origin status is 502 and it is reported here as 503 because Cloudflare replaces 502 and 504 bodies with its own page. This request is never billed: the customer received no data. |
| 503 | Temporarily Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)