What is lookupStatus?
lookupStatus is a documented field on many Social Fetch success responses. It states the outcome of a public lookup (for example found, not_found, or private) inside HTTP 200 so your code does not infer meaning from missing nested fields.
Why it exists
Scrapers and unofficial APIs often return 200 with an empty object when a profile is private or missing. That forces every client to invent heuristics.
Where a route documents lookupStatus, read it before writing to a warehouse. Retry policy should treat not_found differently from a 503.
Credits and lookupStatus
A completed lookup that returns private or not_found still consumed work. On Social Fetch those outcomes meter credits when the route docs say so. See /docs/credits.
List routes that omit lookupStatus say so in OpenAPI. Often you call a profile GET first when you need an explicit outcome.
Common values
found means you got a usable payload. not_found and private mean the lookup finished and there is nothing to invent. Some Instagram post routes also document restricted for age-gated or otherwise non-scrapable media.
Exact enums live on each operation schema and in /docs/capability-matrix. Do not assume every platform returns the same set. Treat not_found as terminal for that handle unless your product expects the account to appear later.
FAQ
Is lookupStatus on every route?
No. It appears where the operation documents it. Check the capability matrix and the per-operation schema.
Should I retry not_found?
Usually no. Retry transport failures and 503s. Do not burn credits re-fetching a confirmed missing handle in a tight loop.
Where is this spelled out?
/docs/errors and /docs/capability-matrix. The unified schema page covers the envelope around it.