# Reverse Face Search (`taupe_thrush/reverse-face-search`) Actor

Reverse image search for faces. Give it a photo URL and get back the pages and images where that person appears on the web, ranked by similarity, with same-person matches flagged. Your photo is never stored. Run it as a job or call it live in Standby mode.

- **URL**: https://apify.com/taupe\_thrush/reverse-face-search.md
- **Developed by:** [MT](https://apify.com/taupe_thrush) (community)
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $50.00 / 1,000 face searches

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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. |

```json
{
    "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:

```json
{
    "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:

```json
{
    "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](https://docs.apify.com/platform/actors/development/programming-interface/standby),
so you get results in a single HTTP request instead of starting a run and polling:

```bash
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.

# Actor input Schema

## `imageUrl` (type: `string`):

Public http(s) URL of the photo to search with. The image is downloaded into memory, matched, and discarded — it is never stored. JPEG, PNG, WebP, GIF, BMP and TIFF are supported (HEIC, AVIF and SVG are not).

## `maxResults` (type: `integer`):

How many similar faces to return, ranked by similarity. The backend considers the 200 nearest indexed faces, so 200 is the ceiling.

## `minSimilarity` (type: `number`):

Drop matches whose cosine similarity is below this value (0–1). The backend's own match threshold is 0.30; leave at 0 to get the full ranked list padded out to N.

## `samePersonOnly` (type: `boolean`):

Return only faces the backend clustered as the same person as the query, without padding the list out to N with merely similar faces. Can return fewer than N results — or none.

## Actor input object example

```json
{
  "imageUrl": "https://example.com/photo.jpg",
  "maxResults": 20,
  "minSimilarity": 0,
  "samePersonOnly": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "imageUrl": "https://example.com/photo.jpg"
};

// Run the Actor and wait for it to finish
const run = await client.actor("taupe_thrush/reverse-face-search").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "imageUrl": "https://example.com/photo.jpg" }

# Run the Actor and wait for it to finish
run = client.actor("taupe_thrush/reverse-face-search").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "imageUrl": "https://example.com/photo.jpg"
}' |
apify call taupe_thrush/reverse-face-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,taupe_thrush/reverse-face-search"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/AZZDmvXi2oAYyYmmc/builds/YecZt8vweDAD6BSmd/openapi.json