Skip to main content
POST
Estimate
A dry run over a list: how many of these addresses are in the index, how many we checked and found bare, how many we have never seen, and the band a resolve would bill inside. Counts only, never identities. Use it to decide whether a list is worth spending on, and which endpoint to spend on, before anything bills. It costs no match credits, at any balance, so a drained key can plan the purchase that refills it. It weighs the rate window exactly like the batch it previews, one unit per address, and the list is capped at your plan’s max_batch_size. The minimum is 10 distinct addresses, because the counts are aggregates by design; for one address, resolve it.

Request

string[]
required
10 to max_batch_size addresses. Duplicates are removed before counting; at least 10 distinct addresses must remain.

Response

number
Distinct addresses after deduplication.
number
Addresses holding at least one identity: X, Farcaster, ENS, Lens or GitHub.
number
Addresses we checked and found bare. Resolving these is free and unlikely to find anything until the negative record ages out.
number
Addresses the index has never seen. A plain batch returns null for these; a job resolves them against live sources.
object
low, high and a note saying how to read them.

Reading the band

low is exact, not an estimate: it is what a batch of this list bills today, because a batch bills the addresses already holding an X handle or a Farcaster account. It can sit below in_index, because an address carrying only an ENS name, a Lens profile or a GitHub account is returned and never billed. high adds the never-checked addresses at the measured overall match rate. A job resolves those against live sources, so high is the job-shaped ceiling; a plain batch stays at low. It is a band, not a quote: match rates differ several-fold by chain, and an address does not say which chain its holder community lives on. Take the measured per-chain table from GET /v1/stats match_rates and use the row for your chain.

Errors

The standard errors, plus LIST_TOO_SMALL (400) when fewer than 10 distinct addresses remain after deduplication, and BATCH_SIZE_EXCEEDED (400) when the list is over your plan’s ceiling; the message names it.