Bulk valuation jobs

A bulk job takes a list of up to 1,000 sites and works through it in the background: sites mxverify already values are answered at once, and sites it has never valued are valued as the job reaches them. Partner keys only.

Start a jobCopy Anchor Link

POST /api/v1/bv/valuations
Content-Type: application/json

{"targets": ["site-one.com", "site-two.com", "..."]}

curl https://mxverify.uk/api/v1/bv/valuations \
  -H "Authorization: Bearer mxk_partner_key" \
  -H "Content-Type: application/json" \
  -d @targets.json

The answer is 202, with a Location header:

{
  "id": "4f1c2b9a8d7e4c3fa1b2c3d4e5f60718",
  "status": "running",
  "total": 1000,
  "done": 3,
  "status_url": "https://mxverify.uk/api/v1/bv/valuations/4f1c2b9a8d7e4c3fa1b2c3d4e5f60718"
}

• Every target is a lookup, taken from the key's day when the job starts (so done already counts targets that are not website addresses).
• If the key's lookups for the day are used, or a partner balance does not cover them, the job is refused with 429 before it starts.
• A key can run 3 jobs at once.

Read a jobCopy Anchor Link

GET /api/v1/bv/valuations/{id}

{
  "id": "4f1c2b9a8d7e4c3fa1b2c3d4e5f60718",
  "status": "running",
  "total": 1000,
  "done": 420,
  "created_at": "2026-10-25T12:00:00.000Z",
  "results": [
    { "target": "site-one.com", "status": "valued", "bv": { "usd": 64.5, "per": "followed link", "level": "B", "caps": "", "version": "2.8", "audited": false }, "report_url": "https://mxverify.uk/publications/site-one.com", "attribution": { "text": "BV by mxverify", "url": "https://mxverify.uk/publications/site-one.com", "required": true } },
    { "target": "site-two.com", "status": "pending", "bv": null }
  ]
}

• results has one entry per target, in the order sent, each a result object or pending.
• While status is running, the answer carries Retry-After: 30. Read it no more often than that.
• When every site is answered, status is done and finished_at is set.
• Reading a job is free: it is not a lookup.
• A job belongs to the key that made it, and is kept for a week.

How sites are valued in a jobCopy Anchor Link

Each site a job reaches is handled exactly as a lookup would handle it, at that moment:

• a site with a report: its figure;
• a site never valued: valued now, from the free allowance first and then, for a partner, paid from the balance;
• past the key's valuation limit, or with no balance left: not_valued, with the reason;
• a site another caller is valuing at the same moment: not_valued ("being valued now"); look it up in a minute.

If the key is revoked while the job runs, the remaining sites answer not_valued. If the account's partner access is paused, the job carries on at the free limits.

PaceCopy Anchor Link

Jobs share mxverify's work queue and advance a few sites at a time, so a 1,000-site job with many new sites takes tens of minutes. Known sites go fastest. Once a job is done, keep the answers and refresh them with ordinary lookups; see caching.