Reverse Face Search

Give it the URL of a photo. It finds the face in that photo and returns the URLs of the most similar faces found on the web, ranked by similarity.

The query photo is downloaded into memory, matched, and dropped. It is never stored — not on disk, not in any bucket, not in the Actor's storage. Only the URLs of the matches are written to the dataset.

Input

Field	Type	Default	Description
imageUrl	string	—	Required. Public http(s) URL of the photo to search with.
maxResults	integer	20	How many similar faces to return (N). 1–200.
minSimilarity	number	0	Drop matches below this cosine similarity (0–1).
samePersonOnly	boolean	false	Return only the faces judged to be the same person, with no padding. May return fewer than N, or none.

{
    "imageUrl": "https://example.com/photo.jpg",
    "maxResults": 10
}

Supported formats: JPEG, PNG, WebP, GIF, BMP, TIFF, up to 10 MB. HEIC, AVIF and SVG are rejected with a clear error rather than silently failing to find a face.

Output

One dataset row per matched face, best first:

{
    "rank": 1,
    "similarity": 0.8123,
    "matchPercent": 81.2,
    "samePerson": true,
    "imageUrl": "https://cdn.example.com/images/group-photo.jpg",
    "pageUrl": "https://example.com/news/story",
    "imageDomain": "cdn.example.com",
    "pageDomain": "example.com"
}

• imageUrl — the matched photo itself. pageUrl — the page that embedded it. A face is only returned if it has at least one of the two.
• samePerson — true while the results come from the same-person group. Once that group is exhausted the list is padded with the next-most-similar faces, which are false. Set samePersonOnly if you only want the former.

The run also writes a summary to the OUTPUT key-value record:

{
    "queryFaceFound": true,
    "threshold": 0.3,
    "candidatesConsidered": 200,
    "matchCount": 4,
    "resultCount": 10,
    "results": [...]
}

queryFaceFound: false means no face was detected in the query photo — the run succeeds with zero results rather than failing.

Use it as an API

The Actor also runs in Standby mode, so you get results in a single HTTP request instead of starting a run and polling:

curl "https://<your-standby-url>/search?imageUrl=https%3A%2F%2Fexample.com%2Fphoto.jpg&maxResults=10&token=<APIFY_TOKEN>"

curl -X POST "https://<your-standby-url>/search?token=<APIFY_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{"imageUrl": "https://example.com/photo.jpg", "maxResults": 10}'

The response is the same envelope as the OUTPUT record, and the full API is documented on the Actor's Standby tab. GET / returns a short usage blurb.

Errors come back as {"error": "..."} with a meaningful status: 400 bad input or undownloadable URL, 402 the run's charging limit is reached, 413 image too large, 415 unsupported format, 502 the search service is unavailable.

Notes and limits

• Only the largest face in the query photo is matched. Crop to the face you want if the photo has several people.
• maxResults is capped at 200.
• A clear, front-facing, reasonably sharp photo matches far better than a small or heavily angled one.
• Results are drawn from images crawled from the public web. Absence of a match is not evidence that a person has no photos online.