Bulk and async jobs: API v4

Two paths exist for more than one domain. Pick by size and by whether you want to wait.

Bulk Async batch
Endpoint POST /api/v4/categorize/bulk POST /api/v4/categorize/batch/async
Domains per call Up to 100 Up to 10,000
Response Results, synchronously A job_id, immediately
You then Read the results Poll, or receive a webhook
Billing 1 credit per domain with a result 1 credit per domain with a result

Bulk — up to 100 domains

Classify up to 100 domains in one call. The results come back synchronously, one row per domain, in the order you sent them.

curl -X POST "https://website-categorization.whoisxmlapi.com/api/v4/categorize/bulk?apiKey=YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domains": ["stackoverflow.com", "github.com", "example.com"]}'

Request body

Field Type Required Description
domains array Yes Domains to categorize. Maximum 100 entries.
skip_cache boolean No Accepted, but currently has no effect on bulk. Use the single-domain endpoint or an async job to force a fresh classification.

Response

{
  "results": [
    {
      "domain": "stackoverflow.com",
      "categories": [
        {
          "id": "IAB-631",
          "iab_id": "IAB-631",
          "name": "Programming Languages",
          "tier1": "Technology & Computing",
          "tier2": "Computing",
          "tier3": "Programming Languages",
          "tier4": null,
          "confidence": 0.99,
          "path": "Technology & Computing > Computing > Programming Languages"
        }
      ],
      "primary_category": {
        "id": "IAB-631",
        "iab_id": "IAB-631",
        "name": "Programming Languages",
        "tier1": "Technology & Computing",
        "tier2": "Computing",
        "tier3": "Programming Languages",
        "tier4": null,
        "confidence": 0.99,
        "path": "Technology & Computing > Computing > Programming Languages"
      },
      "abstain": { "is_abstain": false, "reason": null },
      "source": { "is_historical_fallback": false, "kind": "live" },
      "error": null
    }
  ],
  "total": 3,
  "successful": 3,
  "credits_charged": 3,
  "taxonomy_version": "iab_v3.1",
  "latency_ms": 215.4
}

The example above shows the first row only; two more rows are elided, one for each remaining submitted domain.

Field Description
results One row per submitted domain, same order as sent.
total Domains submitted.
successful Domains that returned a result.
credits_charged Credits for the whole batch.
taxonomy_version Always iab_v3.1 today.
latency_ms Server-internal time for the batch.

Per-domain errors, not batch failure. If one domain fails you still get 200 with a row for every domain — check each row's error. Failed rows are not charged. When a domain's name servers do not answer in time, its row's error reads temporary DNS failure (dns_timeout): retry this domain: send that domain again. Submitting more than 100 domains returns 422.

Classification runs concurrently server-side, so a bulk call is substantially faster than the same domains one at a time.

Opt-in blocks work per row. include=policy, include=safety, include=content_purpose and include_status=true append their block to every result row, built from that row's own result. A row that failed still carries every requested block rather than omitting it: is_parked is false, safety.status is not_assessed with no flags, content_purpose is null, and policy.pack and policy.pack_version are populated while group and basis are null and candidate_groups is [].

Async batch — up to 10,000 domains

Submit and walk away. The call returns immediately with a job identifier.

curl -X POST "https://website-categorization.whoisxmlapi.com/api/v4/categorize/batch/async?apiKey=YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "domains": ["stackoverflow.com", "github.com"],
           "webhook_url": "https://example.com/hooks/webcat"
         }'

Request body

Field Type Required Description
domains array Yes Domains to categorize. Maximum 10,000 entries.
webhook_url string No URL to POST a completion notification to. See below.
skip_cache boolean No Defaults to false.

Response — 202 Accepted

{
  "job_id": "9f3a1c62-4d7e-4b19-9a02-1e6f8c40b7d5",
  "status": "pending",
  "total_domains": 2,
  "submitted_at": "2026-09-11T09:15:00.412873+00:00",
  "webhook_url": "https://example.com/hooks/webcat",
  "poll_url": "/api/v4/jobs/9f3a1c62-4d7e-4b19-9a02-1e6f8c40b7d5"
}

poll_url is a path, not a full URL: request it from the same host and add your apiKey, as in Polling a job below.

Jobs are kept for at least 24 hours after submission. Collect your results inside that window.

Async submission accepts an Idempotency-Key request header: a retried submit carrying the same key within 24 hours returns the original job rather than creating a duplicate.

Webhooks

Supply webhook_url and we POST a completion notification to it. The URL must use http or https and resolve to a publicly routable address — anything else is rejected at submission with 400. The notification is a JSON body with job_id, status, total, completed and failed; read the results by polling the job. A webhook is a convenience, not a guarantee: keep polling as your fallback.

Polling a job

curl "https://website-categorization.whoisxmlapi.com/api/v4/jobs/JOB_ID?apiKey=YOUR_API_KEY"
{
  "job_id": "9f3a1c62-4d7e-4b19-9a02-1e6f8c40b7d5",
  "status": "processing",
  "total_domains": 2,
  "completed_domains": 0,
  "failed_domains": 0,
  "progress_pct": 0.0,
  "results": null,
  "created_at": "2026-09-11T09:15:00.412873+00:00",
  "updated_at": "2026-09-11T09:15:00.412873+00:00",
  "error": null,
  "results_total": null,
  "results_limit": null,
  "results_offset": null,
  "credits_charged": null
}

status is one of pending, processing, completed or failed. completed_domains counts every domain that has finished, failed ones included, and failed_domains counts the failed ones. A job whose status is failed has no results and is not charged.

A poll shows the job as last saved, and progress is saved every 10 finished domains. completed_domains, failed_domains, progress_pct and updated_at change only at every tenth finished domain and when the job ends, so a job of fewer than 10 domains shows no progress until it ends, as in the example above.

If a service restart stops a job, the job normally ends failed, is not charged, and its error reads interrupted by a server restart (restart): not charged; submit the job again, with a new Idempotency-Key if you used one: submit its domains again in a new job, with a new Idempotency-Key if you send one.

If a job's updated_at has not changed for 30 minutes (for example, after a service crash), submit its domains again with a new Idempotency-Key. updated_at moves only every 10 finished domains, so a working job can sit unchanged for some minutes. A job is charged once, as it completes, so a job that stops before then is not charged. A stop at that exact moment can rarely leave a job processing after it was charged, even if its credits_charged is still null. If such a job shows credits_charged above 0, or your balance suggests it was charged, contact [email protected] before you submit it again.

Only the API key that submitted a job can read it. An unknown job and someone else's job return the identical 404, so a foreign caller cannot confirm that a job id exists.

Reading results

Once status is completed, results is populated and paginated, up to 10,000 rows per page (1,000 by default):

curl "https://website-categorization.whoisxmlapi.com/api/v4/jobs/JOB_ID?apiKey=YOUR_API_KEY&limit=500&offset=0"

The response echoes results_limit and results_offset, and results_total gives the full row count. Page until offset >= results_total.

Rows come back in the order the domains finished, not the order you sent them. Match each row to your input by its domain, comparing it with both the name exactly as you sent it and its normalized form. On a row we classified, domain is the normalized name: lowercase and trimmed, with no scheme, port, path, query or trailing dot, every leading www. removed, and an international name in punycode. Matching is simplest if you send names already in that form — example.com, not https://www.Example.com/ — with any international name already in punycode: a classified row's domain is then the name you sent. A row with an error may carry the name as you sent it or the normalized name, and after an internal error its domain can be empty. Treat any input that matches no row by either name as failed and submit it again in a new job, with a new Idempotency-Key if you send one.

credits_charged on a completed job is what the job actually cost — one credit per successfully categorized domain. It is normally null until the job completes.

A completed job's rows are not shaped like bulk rows. They carry domain, url, categories, primary_category, is_parked, is_cached, latency_ms, error, domain_status, domain_status_signals, staleness, last_known_category and v3_created_date. There is no abstain or source block, the domain-status keys are always present (async has no include_status parameter), and each category carries id but not iab_id or name. If you need abstain, source, iab_id, name or the policy block, use POST /api/v4/categorize/bulk. v3_created_date is always null: it stays in the row for compatibility, so do not build on it.

Check each row's error. When a domain's name servers do not answer in time, its row carries no category, is not charged, and its error reads temporary DNS failure (dns_timeout): retry this domain: submit that domain again in a new job, with a new Idempotency-Key if you send one.

A completed job's body carries every field of the polling example above. This excerpt shows its first row and the paging fields:

{
  "results": [
    {
      "domain": "stackoverflow.com",
      "url": "https://stackoverflow.com",
      "categories": [
        {
          "id": "IAB-631",
          "tier1": "Technology & Computing",
          "tier2": "Computing",
          "tier3": "Programming Languages",
          "tier4": null,
          "confidence": 0.99,
          "path": "Technology & Computing > Computing > Programming Languages"
        }
      ],
      "primary_category": {
        "id": "IAB-631",
        "tier1": "Technology & Computing",
        "tier2": "Computing",
        "tier3": "Programming Languages",
        "tier4": null,
        "confidence": 0.99,
        "path": "Technology & Computing > Computing > Programming Languages"
      },
      "is_parked": false,
      "is_cached": true,
      "latency_ms": 0.8,
      "error": null,
      "domain_status": "active",
      "domain_status_signals": null,
      "last_known_category": null,
      "staleness": null,
      "v3_created_date": null
    }
  ],
  "results_total": 2,
  "results_limit": 500,
  "results_offset": 0
}

Listing your jobs

curl "https://website-categorization.whoisxmlapi.com/api/v4/jobs?apiKey=YOUR_API_KEY&limit=20&offset=0"
{
  "jobs": [
    {
      "job_id": "9f3a1c62-4d7e-4b19-9a02-1e6f8c40b7d5",
      "status": "completed",
      "total_domains": 2,
      "completed_domains": 2,
      "failed_domains": 0,
      "progress_pct": 100.0,
      "created_at": "2026-09-11T09:15:00.412873+00:00",
      "updated_at": "2026-09-11T09:16:10.927104+00:00",
      "poll_url": "/api/v4/jobs/9f3a1c62-4d7e-4b19-9a02-1e6f8c40b7d5"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}

Jobs submitted with the presenting key, newest first, up to 100 per page (20 by default).

One pagination quirk to code around: a page can contain fewer than limit items while older jobs still remain, because jobs that expired since you last looked are filtered out as the page is read. Page until you get an empty page rather than stopping at the first short one.

Choosing between them

  • Up to 100 domains and you want the answer now — bulk.
  • Thousands of domains, or you would rather not hold a connection open — async.
  • Async submission returning 503 — the message points you at the bulk endpoint. Use it, or retry.
  • Policy pack — the include=policy block that bulk rows can carry.
  • Domain-status fields — how to read domain_status, is_parked and staleness.
  • Error codes — the 400, 404, 422 and 503 contracts these endpoints return, and the per-row error an unsafe target or a DNS timeout produces.

Both paths bill identically: one credit per domain that returns a result, and nothing for domains that do not.