The search the Search page runs. mode "grid" lays a grid of points across each area and densifies where it keeps finding new businesses, which is the method that found 1,061 roofing contractors in Houston where paging deeper from one centre found 255. mode "city" pages from each area's centre and is cheaper for small towns.

Areas are "Houston, Texas", {name, state}, or an id from GET /api/v1/areas. A name that fits more than one place (the US area list has 13 Springfields, and "Houston" alone could be in Texas, Missouri, Mississippi or Alaska) is never guessed: the whole request returns 400 with ambiguous[].candidates, each carrying an id, label, population and coordinates, and nothing is charged. Resend with the id you mean. An unknown name returns 400 with suggestions. Size a grid first with POST /api/v1/searches/estimate.

One lead per NEW listing; listings you already hold cost nothing, ever, and fetching pages carries a small per-page minimum. Areas your account already covers for this query are skipped. At most 2 searches run at once per account, and re-sending an identical search while it runs returns the running job instead of starting a second.

Returns job_id immediately. Poll GET /api/v1/searches/{id}, or subscribe a webhook to job.completed. Read the rows with GET /api/v1/searches/{id}/results. Every new business is enriched automatically as it lands.

{
  "query": "roofing contractor",
  "country": "United States",
  "areas": [
    "Houston, Texas"
  ]
}