TRACE / AI FACE SCAN API

AI FACE SCAN API

AI FACE SCAN,
FROM YOUR OWN CODE.

A reverse face search API over the public web. Send one photo of a face, get back the pages and profiles that face appears on, each with a confidence score and a link. One credit per search, priced in dollars, with no subscription and no monthly minimum.

Get an API key Read the full reference

No sales call · No monthly minimum · Credits never expire

Results in about a minute
One credit per search
REST + JSON, nothing to install
Our own engine, not a reseller

curl -X POST https://traceaifacescan.app/api/v1/scans \
  -H "Authorization: Bearer trk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -F [email protected]

{
  "id": "01m0jr1j5cbhwqsnt5qjx3zyd8",
  "status": "queued",
  "progress": 0,
  "locked": false,
  "match_count": 0,
  "credits_remaining": 9
}

WHAT THE API DOES

ONE PHOTO IN. EVERY PUBLIC MATCH OUT.

The same engine the panel runs on, with the same results. The API is not a cut-down tier.

REVERSE FACE SEARCH

Match a face, not a file.

A normal reverse image search finds copies of the same image. This matches the face, so a different photo of the same person — different outfit, different year — still comes back as a hit.

CONFIDENCE SCORE

Every match carries a number.

Each result has a similarity score from 50 to 100 and a band: possible from 70, strong from 80, near-certain from 90. Nothing is returned as a verdict.

SOCIAL HANDLES

The account, not just the page.

Where the URL belongs to an account, the handle and platform come back as separate fields — no parsing URLs on your side.

OUR OWN ENGINE

Not a reseller.

Trace runs its own face search service. That is why a search costs cents rather than dollars, and why we do not have to meter your requests.

QUICKSTART

THREE CALLS, START TO FINISH.

Authentication is one header. There is no SDK to install and no handshake.

Start a scan

Multipart, field name image. JPEG, PNG or WebP, up to 8 MB, at least 200px on the short side. Idempotency-Key is optional and makes a retry safe.

curl -X POST https://traceaifacescan.app/api/v1/scans \
  -H "Authorization: Bearer trk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -F [email protected]

202 ACCEPTED

{
  "id": "01m0jr1j5cbhwqsnt5qjx3zyd8",
  "status": "queued",
  "progress": 0,
  "locked": false,
  "match_count": 0,
  "credits_remaining": 9
}

Poll until it finishes

A search takes about 25–45 seconds. Poll every second or two until status is done or failed.

curl https://traceaifacescan.app/api/v1/scans/01m0jr1j5cbhwqsnt5qjx3zyd8 \
  -H "Authorization: Bearer trk_live_..."

200 OK

{
  "status": "done",
  "progress": 100,
  "locked": false,
  "match_count": 2,
  "matches": [
    {
      "score": 88,
      "tier": "strong",
      "platform": "x",
      "handle": "@alexrivers88",
      "url": "https://x.com/alexrivers88",
      "preview_url": ".../scans/01m0.../previews/0"
    }
  ]
}

03
Spend the credit

A scan created with no credits available comes back locked: true with no matches — nothing was searched. Revealing is a separate call on purpose: a script walking a list of scans should not be able to empty your balance by accident.
```
curl -X POST \
  https://traceaifacescan.app/api/v1/scans/01m0.../reveal \
  -H "Authorization: Bearer trk_live_..."
```

ENDPOINTS

THE WHOLE SURFACE.

Seven endpoints. The machine-readable definition is at openapi.json, and the full reference with response bodies is in the docs.

POST/v1/scansStart a scan from a photo.
GET/v1/scans/{id}Status, progress and matches.
GET/v1/scansYour scans, paginated.
POST/v1/scans/{id}/revealSpend a credit and run the real search.
GET/v1/scans/{id}/previews/{n}The face thumbnail of one match.
DELETE/v1/scans/{id}Delete the scan, its image and its previews.
GET/v1/accountYour credit balance.

ERRORS AND LIMITS

PREDICTABLE FAILURES.

Errors come back as application/problem+json with a stable code string. Match on the code, never on the message.

402insufficient_creditsNo credits left. Nothing was searched and nothing was charged.
404no_face_detectedNo face in the image. A different photo, not a retry.
429rate_limitedOnly after repeated failed authentication. Retry-After says when.
401unauthorizedMissing, wrong or revoked key.
503provider_unavailableOur side. A credit reserved for a failed search is always returned.

Limits

No request rate limit. Reads are not counted and there is no per-minute ceiling.
Your real limit is your credit balance: a scan costs a credit, a read costs nothing.
Images up to 8 MB, at least 200px on the short side.
Scans and their images are deleted after 30 days. DELETE does it immediately.

PRICING

ONE CREDIT, ONE SEARCH.

The same credits the panel uses, from the same balance. No subscription, no monthly minimum, and they never expire. The 100-credit pack is the one the API is built around.

Bought with Telegram Stars or with cryptocurrency — see the credit packs. Need volume beyond the largest pack? Write to us.

HONEST LIMITS

WHAT THIS API WILL NOT DO.

It is not an identity service. A match is a similarity score between two images, not a statement about who someone is. There is no name, no address, no phone number and no record of any kind in the response — only public URLs and a number.

An empty result is not proof of absence. It means nothing was found on the part of the public web we can reach. If the person has no public photo, there is nothing to find, and no API can change that.

Nothing behind a login is touched. Every result is a page that was already public.

It must not be used for background checks, hiring, lending, insurance, surveillance or law enforcement, and not against minors. Only send photos you have the right to search. This is in the Terms of Use and we enforce it — a key used this way gets revoked.

FAQ

WHAT DEVELOPERS ASK FIRST.

What is an AI face scan API?

It is an HTTP API that takes a photograph of a face and returns the other places on the public internet where the same face appears. Unlike a reverse image search, which compares image files, an AI face scan compares facial geometry — so it matches the same person in a completely different photo. Trace's version is a REST API with JSON responses: one POST to start a scan, one GET to read the matches.

How much does a face search cost through the API?

One credit per search, and credits are bought in packs priced in US dollars — from $5 for 3 credits to $120 for 100. There is no subscription, no monthly minimum and no expiry. The API spends the same balance as the panel.

Do you have a free tier or a trial?

There is no free search on the API. An API request from an account with no credits creates the scan but does not search it: it comes back locked with no matches. The panel shows a signed-in visitor a static sample result so they can see the shape of a finished case, and the API deliberately never returns that — a placeholder is something a script would build on.

How fast is a search?

About 25 to 45 seconds end to end, sometimes up to 90. The API is asynchronous for that reason: POST returns 202 immediately with an id, and you poll it. Holding an HTTP request open for a minute would make a closed connection into a cancelled search.

Can I use image URLs instead of uploading a file?

Not in v1. Accepting a URL would turn the API into an SSRF proxy — we would be fetching arbitrary addresses on a caller's behalf from inside our network. If it comes back it will be with an allowlist and private ranges refused.

Is the API rate limited?

No. Call it as fast as your code can — reads are not counted and there is no per-minute ceiling. The only thing that limits you is your credit balance, because a scan costs a credit and a read costs nothing. One security throttle remains and a valid key never sees it: repeated failed authentication attempts from the same address are slowed down, so guessing keys stays expensive.

Is it legal to use a face search API?

It depends entirely on what you use it for and where you are. Verifying that a photo on your own platform belongs to the person using it is a different thing from building a database of faces. Face data is a special category under GDPR and KVKK, and you are the controller for whatever you send us. Read the Terms of Use: background checks, hiring, lending, insurance, surveillance and law enforcement are all out of bounds.