What is lookupStatus?
lookupStatus is a documented field on many Social Fetch success responses. It states the outcome of a public lookup — found, not_found, private, and so on — inside HTTP 200 so your code reads an explicit answer instead of inferring from empty objects or missing fields.
What the field actually tells you
lookupStatus lives under data on routes that document it. found means a usable payload came back. not_found means the platform confirmed nothing exists at that handle or ID. private means the account or content exists but isn't public. Some routes — Instagram post lookups in particular — also document restricted for age-gated or non-scrapable media.
Values are per-operation, not global. Check each route's schema and /docs/capability-matrix — don't assume every platform shares one enum.
Why HTTP 200 is the correct status here, not an error
A response with lookupStatus: "not_found" is still HTTP 200. The request succeeded — Social Fetch validated it, reached the platform, and got a definitive answer. "This handle doesn't exist" is that answer.
401, 429, 500, and 503 mean something failed before or during execution. lookupStatus on 200 is a completed lookup with a negative outcome — not the same bucket. Collapsing those is the most common integration mistake.
A concrete example
A deleted TikTok handle returns HTTP 200 with data.lookupStatus: not_found, platform fields absent or null, and meta carrying requestId, creditsCharged, and version. No error object — the outcome lives only in data.lookupStatus.
An expired API key returns 401 with a typed error envelope — no data.lookupStatus, because the lookup never ran.
How to branch on it correctly
Check data.lookupStatus before touching other data fields. Treat found as the only case where the rest of the payload is guaranteed populated; not_found, private, and restricted are terminal outcomes for that call.
If a handle worked yesterday and returns not_found today, check lookupStatus first — HTTP status will be 200 either way. If you believe the result is wrong, use meta.requestId for support — don't retry in a loop. See /glossary/request-id.
Don't retry not_found hoping for a different answer. It bills again for the same outcome. Retry only transport failures: timeouts, lookup_failed, or 503 temporarily_unavailable.
How other APIs typically handle this
Many scraper APIs return 200 with empty objects or null fields for missing or private targets, leaving you to guess whether the scraper broke. Others throw 404 for not_found, mixing normal lookup outcomes with broken routes.
lookupStatus keeps expected negative outcomes explicit and separate from HTTP status, which stays reserved for whether the request itself succeeded.
What lookupStatus is not
Not on every route. List and search endpoints usually don't carry a single lookupStatus — check the operation schema.
Not a transport signal. 503 temporarily_unavailable and lookup_failed mean the call didn't complete and aren't billed — different axis from lookupStatus, which only appears on completed calls.
Not free. Completed lookups that resolve to not_found or private still charge — see /docs/credits. Only lookup_failed and 503 temporarily_unavailable are uncharged.
FAQ
What does lookupStatus not_found mean?
The lookup completed and the platform confirmed there's nothing at that handle or ID. HTTP 200, not a transport failure — billed like any completed lookup.
Why did my API call return 200 with an error-like status?
The request succeeded. data.lookupStatus carries the outcome; HTTP status only says whether processing completed. 401, 429, 500, and 503 are genuine problems.
Should I retry a not_found result?
No. Retry only timeouts, lookup_failed, or 503 temporarily_unavailable — none of those bill.
Does Social Fetch charge credits for a not_found result?
Yes. Any completed lookup — found, not_found, or private — charges. Only lookup_failed and 503 temporarily_unavailable are uncharged.
Is lookupStatus present on every endpoint?
No. Mostly on single-resource GET routes. Check /docs/capability-matrix or the operation schema.
How is lookupStatus different from an HTTP error code?
HTTP errors mean auth, rate limit, or server fault — the lookup didn't finish. lookupStatus only appears on 200 responses where the lookup ran and returned a documented outcome.
What values can lookupStatus have?
Common: found, not_found, private; some routes add restricted. The enum is per-operation — check the route schema.
Where is lookupStatus documented in detail?
/docs/errors, /docs/capability-matrix, /docs/credits, and /unified-schema.