Bulk checks
Submit thousands of domains at once and stream results as they resolve.
A bulk check is an asynchronous job that runs the same check mode across a list of domains. Bulk checks scale to up to one million domains per job.
When to use a bulk check vs single check
- Single check for interactive UI flows ("does this name look available?").
- Bulk check for backend pipelines: nightly brand sweeps, candidate- name evaluation, expiry monitoring across a watchlist.
How a bulk job runs
- You submit a list of domains and a check mode.
- The job is created in
processingstate. The API returns immediately with a job ID. - Workers fan out across the list. Each domain runs through the standard pipeline (cache → Bloom → DNS → RDAP → WHOIS) for the chosen mode.
- Results land in the job's results table as they complete. You can:
- Poll the results endpoint and read pages of completed results.
- Stream via Server-Sent Events – open the stream once, receive completion percentages and individual results as they resolve.
- When the last domain resolves, the job moves to
completed.
Max-age and cache reuse
Each bulk job can specify a max-age – the oldest cached result that
counts as fresh. A job with maxAge: 6h reuses cache entries less than 6
hours old; older entries are re-resolved.
This matters for cost: a bulk-check fan-out across 50,000 domains that's
already been checked recently can run almost free. Without max-age (or
maxAge: 0), every domain is freshly resolved.
Cancellation
You can cancel an in-flight job from the UI or via POST /check/bulk/{id}/cancel. Already-resolved results are kept; pending
domains move to cancelled and don't run. You're billed only for what
ran.
Behaviour and edge cases
- Duplicate domains in the input are deduplicated before fan-out.
- Domains the parser can't normalise (malformed strings, IDN edge cases) appear in the results with an error code and don't count toward billing.
- Job records are retained for the lifetime of your account unless you delete them. Results are paginated and cursor-based.
- Results aren't ordered by input position – they're in resolution order. If you need to correlate, include your row index in your application's mapping when you submit.