# Bulk checks and jobs

A bulk check runs one tool on a list of targets as a job: up to 500 domains for the DNS, email,
certificate and network checks, and up to 100 addresses for the website checks. You can follow the job
while it runs, get a notice when it finishes and export the results.

## Running a bulk check

Open a tool, such as the [DNS lookup](/tools/dns-lookup) or the [SSL checker](/tools/ssl-checker), and
choose **Check many at once** under the form. Paste your targets one per line, or upload a CSV file of at
most 1 MB. Then:

1. Choose **Check cost**. This is a dry run: it lists rows that can't be checked, with their line
   numbers, shows the first rows, and says how many credits the job will hold and the longest it could
   take. Nothing is charged or reserved.
2. Fix the rows it lists, or tick **Skip invalid rows** to run only the valid ones.
3. Optionally give the job a label and pick an alert channel for a notice when it finishes.
4. Choose **Start**. The job opens on its own page under [Jobs](/app/jobs).

Bulk checks unlock after your first credit purchase or plan. Single checks work as usual before that.

## CSV files

A CSV file needs a header row when it has more than one column. Name the target column after the tool's
field or one of `target`, `domain`, `url`, `ip` or `name`. Any other column sets that row's options with
the tool's own option names, for example a `types` column for the DNS lookup; separate list values with
`|`, such as `A|MX`. Commas, semicolons and tabs all work as separators, and the file must be UTF-8.

Options that change a check's price, like rendered mode, apply to the whole job, not to single rows.
Rendered mode and contrast checks aren't available in bulk checks.

Duplicate rows are removed, keeping the first. Website checks take at most 10 rows per site in one job;
for more pages of one site, use the [broken link checker](/tools/broken-link-checker), which crawls.

## What it costs

Each row costs the tool's own price, and cached answers cost the same. When the job starts it holds the
price of every valid row. Each row that gets a result is charged; rows that fail or are skipped cost
nothing, and whatever wasn't used returns to your balance when the job ends. A domain report row that
comes back partial costs the full 10 credits.

## Following a job

The job's page shows its progress live, the time left, the credits held or used, and the finished rows 50
at a time. **Cancel job** stops it: rows already checked keep their results and are charged, and the rest
are skipped and refunded. A job keeps running if you close the page, and survives a restart on our side.

[Jobs](/app/jobs) lists every job of your account, newest first, with filters for running and finished
jobs. Results are kept for 7 days after a job finishes; the job itself is listed for 30 days.

## Notices when a job finishes

Pick any alert channel of your account in the panel: an email channel, a Slack channel, or a webhook. A
webhook made only for job notices needs no monitoring plan. The notice says how many rows were checked,
how many failed and what was charged, with a link to the job; it never lists your targets. See
[webhooks](/docs/webhooks) for how webhook notices are signed.

## Dangling record checks in bulk

A bulk [dangling record check](/tools/subdomain-takeover-check) only runs on domains you control, at most
20 domains per job. The dry run lists a TXT record for each domain that hasn't proved it yet, such as
`_dnssuper-verify.example.com` with the value `dnssuper-verify=…`. Publish the records at your DNS host,
then choose **Check records** in the panel. Nothing is charged until every record is in place. The records
stay valid, so you only publish them once per domain.

## Limits

- At most 3 unfinished bulk jobs per account, and 10 bulk jobs started an hour.
- 30 dry runs an hour.
- A job must be able to finish within about 50 minutes; split a larger list.
- Some tools allow fewer rows than 500; the panel says how many. Ask us if you need more.

## By API

Send `POST /v1/bulk/{tool}` with exactly one of `targets` (names), `rows` (objects of the tool's own
inputs) or `csv` (a CSV file's text), plus job-wide `options`, an optional `label` and `notify` (an alert
channel id). Add `?dry_run=true` to check the list without starting anything, and `?skip_invalid=true` to
run only the valid rows. You can also upload the file itself with `Content-Type: text/csv`, with the
options as query parameters.

The answer is `202` with the job's id and the URLs to follow it: `GET /v1/jobs/{id}` for the status,
`GET /v1/jobs/{id}/items` for the rows, `GET /v1/jobs/{id}/events` as a stream, and
`POST /v1/jobs/{id}/cancel`. `GET /v1/jobs` lists your jobs. A retry with the same `X-Request-Id` returns
the same job without holding credits again.

curl: a dry run, then the job

```sh
curl -X POST "https://api.dnssuper.com/v1/bulk/dns-lookup?dry_run=true" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targets": ["example.com", "example.net"], "options": {"types": ["A", "MX"]}}'

curl -X POST "https://api.dnssuper.com/v1/bulk/dns-lookup" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targets": ["example.com", "example.net"], "label": "Clients"}'

# Or upload a CSV file as it is, with job-wide options in the query string
curl -X POST "https://api.dnssuper.com/v1/bulk/dns-lookup?skip_invalid=true" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @domains.csv
```

Python

```python
import os
import time

import httpx

api = httpx.Client(base_url="https://api.dnssuper.com", headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"})
job = api.post("/v1/bulk/dns-lookup", json={"targets": ["example.com", "example.net"]}).json()
while (status := api.get(f"/v1/jobs/{job['job_id']}").json())["status"] not in ("done", "cancelled", "failed"):
    time.sleep(5)
items = api.get(f"/v1/jobs/{job['job_id']}/items", params={"limit": 100}).json()["items"]
for item in items:
    print(item["row"], item["target"], item["status"])
```

TypeScript

```ts
const headers = { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}`, "Content-Type": "application/json" };
const started = await fetch("https://api.dnssuper.com/v1/bulk/dns-lookup", {
  method: "POST",
  headers,
  body: JSON.stringify({ targets: ["example.com", "example.net"] }),
}).then((response) => response.json());
const job = await fetch(`https://api.dnssuper.com/v1/jobs/${started.job_id}`, { headers }).then((response) => response.json());
console.log(job.status, `${job.done} of ${job.total}`);
```

Tools bulk_run and get_job on https://mcp.dnssuper.com/mcp

```text
bulk_run(tool="dns-lookup", targets=["example.com", "example.net"], dry_run=True)
bulk_run(tool="dns-lookup", targets=["example.com", "example.net"], label="Clients")
get_job(job_id="<job id>", detail="compact")
get_job(job_id="<job id>", detail="full", after=10)
```

Over MCP, `bulk_run` starts a job of up to 500 names and returns at once, and `get_job` follows it, 10 rows
at a time in compact mode or 50 rendered rows with `detail="full"`.

## Questions

### Why does the cost line show fewer rows than my list?

Duplicates are removed and rows that can't be checked are counted apart. Only valid, unique rows are
charged.

### Can I export the results?

Yes: choose JSON, CSV or PDF on the job's page. See [exports](/docs/exports).

### Which tools have bulk checks?

The DNS lookup, availability, DNSSEC, dangling record, email setup, MTA-STS, SSL, IP, ASN and IPv6 checks
take up to 500 rows; the domain report and the website checks (security headers, SEO, structured data,
accessibility, standard files, AI crawlers, tech stack and redirects) take up to 100. Domain reports in bulk
start from the [domain report](/report) page.
