Credits and limits: API v4

What it costs

No existing subscription changes price mid-term, and renewals on or after 23 January 2027 are at the current price list. Your current credits keep their value, and renewals before that date stay at your current price.

New purchases follow the price list on the pricing page. You can buy one-time credit packs, which never expire, or a monthly or yearly plan; a yearly plan costs ten times the monthly price. Larger packs and plans cost less per credit. The free tier is 500 credits. For more than the largest pack or plan (250,000 credits), contact [email protected]. There is no separate onboarding fee.

Website Categorization sells through the WhoisXML platform: you authenticate with your existing WhoisXML API key, and each billable call draws credits from your account balance. There is no separate Website Categorization subscription or dashboard.

What consumes a credit

Opt-in blocks are free. Requesting include=policy, include=safety, include=content_purpose, include_status=true, output_format=openrtb or output_mode=set never changes what a call costs. They are projections of a classification you already paid for.

What does not cost a credit

You are not charged when there is nothing useful to bill for:

• Calls that return no category. A result with categories: [] is not billed. That includes parked and inactive domains, and a site we tried to read today and could not (domain_status blocked, unreachable or error). A result flagged abstain.is_abstain: true that still carries a category is billed.
• Parked and non-classifiable domains. No categories, no charge, whether or not you requested the domain-status block.
• Failed rows in a bulk request or an async job. You pay only for domains that come back with a result.
• Rate-limited (429) and rejected (503) requests. Never billed.
• Errors generally. No error response is billed.

A domain answered from our curated list, a domain-name rule or the cache keeps its category and bills normally, even if the site blocks us today.

Cached calls are billed

A repeat classification of the same domain within the cache window still returns a result and is billed the same as a fresh one. The credit price does not change based on whether your particular request happened to hit the cache.

Retries and billing

Send an Idempotency-Key request header. A retry carrying the same key within a 24-hour window is processed again (usually from the cache) but normally charges credits_charged: 0 if an earlier request with that key was already billed; a retry after a 429 or 503 bills normally. On the bulk endpoint the key covers the whole batch. On async submission a retry with the same key returns the original job; the job is charged once, when it completes.

Use a stable key per logical request, not a fresh one per attempt.

Reading what you were charged

Every categorization response carries credits_charged, and an async job reports it once it completes. Read it rather than counting your own requests — it is the authoritative record, and several situations return a result while charging nothing.

Bulk responses carry a batch total; a completed async job carries the job total.

Rate limits

Requests are limited per API key, using a token bucket. The defaults are 600 requests per minute sustained with a burst capacity of 100.

Your account's configured limits may differ — check your dashboard or ask support for your tier.

Exceeding a limit returns 429 with a Retry-After header giving the seconds to wait. Honour it; do not retry in a tight loop. A second, independent throttle exists on the billing side and behaves the same way. Neither charges you.

Request size limits

Exceeding a size limit returns 422.

Service commitments

• Uptime: 99.0% monthly, measured as the percentage of 1-minute windows in a calendar month during which the API returns a non-5xx response to a valid, authenticated request.
• Latency: p95 response time of 25 seconds or less for POST /api/v4/categorize on a cache-miss request, measured end to end from request receipt to response.

A cache miss means a live fetch and classification of a site we have not seen recently, which is why the commitment is measured in seconds rather than milliseconds. Cached results return far faster, and supplying your own title, description and body_text removes the fetch from the path entirely.

Support response times

Business days are Monday to Friday, excluding public holidays observed by WhoisXML.

Service credits

If monthly uptime falls below the commitment:

Request a service credit within 30 days of the end of the affected billing period; confirmed credits are applied within 10 business days.

Planning for volume

Talk to us before you provision at volume if either of these describes your traffic:

• Your workload's cache-hit rate is low — mostly first-time lookups on domains we have not classified recently.
• You expect more than 250,000 calls per month before you have a measured cache-hit rate for your own traffic.

Both cases change how the service behaves for you, and both are easier to size in advance than to fix afterwards.

Related pages

• Account balance information.
• Error codes — the 403, 429 and 503 contracts.
• Bulk and async jobs.