Output format: API v4

A successful POST /api/v4/categorize returns 200 with a JSON object. This page documents every key in it.

A complete response

{
  "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"
  },
  "taxonomy_version": "iab_v3.1",
  "credits_charged": 1,
  "latency_ms": 0.8,
  "model": "curated/manual_curation_2026-05-08",
  "abstain": { "is_abstain": false, "reason": null },
  "source": { "is_historical_fallback": false, "kind": "live" },
  "prediction_set": null,
  "openrtb": null,
  "error": null
}

Top-level fields

Field Type Description
domain string The domain you asked about.
categories array Candidate categories, ordered by model rank. See below.
primary_category object / null The category to use when you want exactly one. null when nothing was classifiable.
taxonomy_version string Always iab_v3.1 today.
credits_charged integer Credits this call actually cost. See Credits and limits.
latency_ms number Server-internal classification time in milliseconds. Excludes the gateway and network round trip, so it reads lower than the time your client measures.
model string / null Which classification path produced the answer.
abstain object Advisory signal with a reason: no real business purpose, or too little text to tell what the site is for. See below.
source object Provenance and freshness of the answer. See below.
prediction_set object / null Calibrated prediction set. null unless you set output_mode=set.
openrtb object / null AdCOM projection. null unless you set output_format=openrtb. See OpenRTB output.
error string / null null on success; a short diagnostic string on a partial or failed classification.

categories[] and primary_category

Both use the same object shape.

Field Type Description
id string / null IAB Content Taxonomy v3.1 identifier, for example IAB-599.
iab_id string / null The same value as id. This is the consistent cross-endpoint key.
name string The most specific category name on the path.
tier1 string Top-level category.
tier2 string / null Second level, when the label has one.
tier3 string / null Third level.
tier4 string / null Fourth level.
path string The full path, for example Technology & Computing > Computing.
confidence number Model confidence for this candidate.

Two things worth knowing:

  • primary_category is categories[0] — the top-ranked candidate. It is not guaranteed to be the numerically highest confidence in the array. If you want exactly one label, use primary_category; that is what it is for.
  • How deep a label goes is not a measure of how much the page supported. For allow/block policy, key on tier1 (or tier1 and tier2) and treat deeper tiers as descriptive detail. A result whose deeper tiers are null is still a valid label.

abstain

{ "is_abstain": true, "reason": "no_business_purpose" }

An advisory signal about the result. When is_abstain is true, reason says why; when it is false, reason is null.

reason Meaning
no_business_purpose The page we classified reads as parked or for sale, or the domain is on our list of ad-technology, DNS, CDN and cloud-hosting zones.
topic_equals_purpose The text we classified was too short to tell what the site is about from what it is for.

A parked or for-sale page and too-short text are judged from the text we classified: the page we read, or the body_text you send. Ad-technology and infrastructure domains are judged from the domain name, against a list of zones we maintain. The list includes CDN and cloud-hosting zones, so a real site hosted on one of these platforms can read is_abstain: true. Listed or not, such a domain is classified like any other: the flag does not remove its category, and an answer with a category is billed. The DNS root servers and reverse-DNS names (root-servers.net, in-addr.arpa, ip6.arpa) are not classified at all: they serve no website, return no category and are not billed. A repeat answer served from our cache, or an answer from our curated list, has no page text to judge, so it can read is_abstain: false where a fresh read flagged a parked site or a short page.

Do not use abstain to find parked domains. It is never judged from domain_status. A domain we find parked or dead before we classify a page returns no category and is not billed, and usually reads is_abstain: false. To find parked and dead domains, request include_status=true and read domain_status.

When is_abstain is true:

  • categories and primary_category are unchanged. An abstain does not clear them, and a result can carry both a category and is_abstain: true. Decide for yourself whether to treat such a result as "no category".
  • Billing follows the result, not the signal: a call that returns a category is billed even when is_abstain is true. Read credits_charged.

source — where the answer came from

{ "is_historical_fallback": false, "kind": "live" }
Field Value Meaning
kind live A fresh or cached live classification of the site as it is today.
kind historical_fallback No longer served. Kept as a documented value so a strict parser keeps accepting it. See below.
is_historical_fallback boolean Always false. See below.

Historical fallback is no longer served. Until the 2 October 2026 update, a result whose domain_status (with include_status=true) is blocked, unreachable or error — a site the service tried to read and could not — could carry the label the legacy WhoisXML v3 service returned for that domain, marked source.is_historical_fallback: true. From that update such a result carries no category. (A domain answered without a read — from the curated list, a domain-name rule or the cache — keeps its category.) source.is_historical_fallback stays in the response and is always false.

Blocked and unreachable sites are real sites we could not read. They are not parked, and a result with no category is not billed.

Calibrated prediction sets (output_mode=set)

By default (output_mode=top1) prediction_set is null and you get one ranked list.

Set output_mode=set to receive, in addition, a prediction set — a subset of the candidates chosen by a conformal calibration procedure so the set carries an approximate coverage guarantee at the level you request. The default response is unchanged: primary_category and categories[] keep exactly the same values.

curl -X POST "https://website-categorization.whoisxmlapi.com/api/v4/categorize?apiKey=YOUR_API_KEY&output_mode=set&coverage=0.65" \
     -H "Content-Type: application/json" \
     -d '{"domain": "stackoverflow.com"}'
{
  "prediction_set": {
    "coverage_target": 0.65,
    "coverage_achieved": 0.65,
    "set": [
      {
        "tier1": "Technology & Computing",
        "tier2": "Computing",
        "confidence": 0.99
      }
    ],
    "capped_at_top3": false,
    "calibration_source": "wave1calibheldout_n426_2026-06-25_customer_lens"
  }
}
Field Type Description
coverage_target number The level you requested.
coverage_achieved number The calibrated level the set was built for: the requested target snapped to the grid. Not a measurement: when capped_at_top3 is true, coverage is at most 0.8405.
set array The prediction set, ordered by confidence. Each entry carries tier1, tier2 and confidence.
capped_at_top3 boolean true when the level your request snapped to is above the ceiling: the set is then the widest the calibration can build.
calibration_source string Identifier of the calibration artifact behind this set.

Three properties to design against:

  1. Targets snap to a calibrated grid. The deployed calibration supports the levels 0.40, 0.50, 0.60, 0.65, 0.90 and 0.95. A request between grid points is served at the nearest calibrated level, and coverage_achieved tells you which calibrated level the set was built for — read it rather than assuming you received coverage_target. The levels from 0.40 through 0.65 currently resolve to the same single-entry set, so asking for 0.50 and 0.65 returns identical output.
  2. There is a ceiling. The deployed calibration artifact records a coverage ceiling of 0.8405 — no prediction set can cover beyond it, because that is the ceiling of the underlying candidate list. Requesting a level above the ceiling returns the widest set the calibration can build and sets capped_at_top3: true; it does not raise coverage past the ceiling. coverage_achieved still reads the snapped level you asked for, 0.90 or 0.95, not the coverage you get.
  3. It is additive. Requesting a set does not change classification, caching or billing.

Request coverage outside 0.01–0.99 and the call returns 422.

Opt-in blocks

These blocks are absent from the default response — not null — and appear only when you ask for them:

Request Adds Documented on
include=policy policy Policy pack
include_status=true domain_status, is_parked, staleness, last_known_category, classified_at, v3_created_date, v3_registration_age_days Domain-status fields
include=safety safety Safety, below
include=content_purpose content_purpose Content purpose, below

For these, check for key presence, not for a null value.

Safety

include=safety adds a safety key: what our brand-safety filters measured on this result, read back from what was stored when the label was produced. It is not a second opinion on the category, and requesting it re-runs nothing.

"safety": {
  "status": "flagged",
  "flags": ["gambling"],
  "verdicts": [
    {
      "filter": "gambling_filter",
      "theme": "gambling",
      "status": "flagged",
      "score": 0.93,
      "scale": "keyword_density",
      "version": "rules@6f1c2a0d9b3e4a71",
      "assessed_at": "2026-09-10T12:00:00+00:00",
      "bypassed": null
    }
  ]
}
Field Type Description
status string flagged (a block-signal theme fired), assessed_clean (a filter reached a decision and nothing a blocker acts on fired) or not_assessed (no brand-safety filter reached a decision on this result).
flags array of string The block-signal themes that fired, sorted. Write your rule against this list. Never null.
verdicts array Every stored reading, block signal or not, each with its filter's own score and the scale it is measured in.

Read not_assessed as "we did not look", never as "clean". assessed_clean means a filter looked and nothing fired; it is not a guarantee that the site is safe, because we have not yet published a measurement of how much unsafe content our filters miss. Each filter scores on its own scale, so never compare or threshold score across filters. A flagged result can carry an empty verdicts list, when one of our content filters wrote its label and its stored readings are missing or unreadable, so match on flags, never on verdicts[0]. The block works on the bulk endpoint per row, and requesting it never changes categories[] or credits_charged.

Content purpose

include=content_purpose adds a content_purpose key: IAB Content Purpose = News, next to the unchanged topic. IAB v3.1 has no News topic, so a news outlet's categories[] carry what it covers (Politics, Sports, Business and Finance and so on); filter news inventory on this block and keep writing topic rules against categories[].

"content_purpose": {
  "id": "1020",
  "name": "News",
  "path": "Content Purpose > Informational > News",
  "source": "curated"
}

source is curated (our reviewed news-publisher list) or schema_org (the site's own NewsMediaOrganization markup). The value is null when you requested the block and neither signal fired: that means unknown, not "not news". The block works on the bulk endpoint per row, and requesting it never changes categories[], a confidence or credits_charged.

prediction_set (output_mode=set) and openrtb (output_format=openrtb) behave differently: both keys are always present, and carry null until you request them. Test the value, not the key.

A note on the bulk data feed

The Website Categorization bulk data feed is a separate product with its own schema and its own release cadence. Where the API and the feed both express a category they use the same IAB v3.1 taxonomy, but they are produced by separate pipelines and are not guaranteed to agree row-for-row on any given domain at any given moment. Do not assume a label seen in one is already present in the other. The feed's own column reference is the authority for feed contents.

Machine-readable schema

An OpenAPI 3.1 document describes every operation, parameter and response object on this API, suitable for code generators such as openapi-generator or swagger-codegen. Download the OpenAPI document.