Understand credits and overage billing

The CaptainDNS public API is metered in credits. A simple DNS lookup costs 1 credit, a deliverability score costs 30. Each plan includes a monthly credit quota; overage is billed at the end of the period for paid plans. This page covers the details.

Principle

A credit is not a unit of time, data, or requests. It is an internal cost unit reflecting the amount of work the CaptainDNS backend performs:

• 1 credit: a cached DNS lookup.
• 2-3 credits: a multi-resolver check or a DNSSEC chain validation.
• 5-6 credits: a multi-RBL blacklist check or a full SMTP test.
• 8-10 credits: an HTTP crawl with metadata extraction or phishing detection.
• 30 credits: a deliverability score aggregating SPF, DKIM, DMARC, BIMI, reputation.

This lets you predict an integration's consumption without needing to compute the exact number of requests: multiply by the average endpoint cost and you have your approximate monthly volume.

Cost per endpoint

The table below is aligned with the OpenAPI specification. If you mirror this table into a third-party system, remember to update it during version bumps. See the OpenAPI reference for the full list of endpoints including text tools (1 credit each).

Plan quotas

Annual billing: 20 % discount (two months free).

Hard cap: the Free plan does not bill overage. Once the 500 credits are consumed, every request returns 403 QUOTA_EXCEEDED until the end of the monthly period. To avoid the cutoff, upgrade to Starter.

Soft overage: paid plans allow exceeding the quota. Overage credits are tracked separately and billed at the end of each month. Actual billing is only triggered after the monthly period closes.

Headers returned by the API

Every API public response includes three accounting headers:

X-Credits-Limit: 50000
X-Credits-Remaining: 37547
X-Credits-Consumed: 2

• X-Credits-Limit: the plan's monthly quota.
• X-Credits-Remaining: credits still available from the included envelope. Once negative, you are in overage (paid plans only).
• X-Credits-Consumed: credits consumed by the current request.

Use these headers to drive your client: log as the quota approaches, trigger an alert at 80 %, queue non-critical calls if you are about to run out.

Check your usage

The CaptainDNS dashboard (Account > API usage) shows the current month and the previous 12 months, with details on credits consumed, overage, and billing history.

Avoid surprises

Upfront estimation: before launching an integration, multiply the expected number of requests by the average cost. A crawler calling page-crawl-check on 10,000 URLs per month consumes 100,000 credits, more than the Starter quota (50,000).

Backoff near the quota: monitor X-Credits-Remaining. When it reaches 10 % of the quota, slow down or queue non-urgent calls.

Deduplication: if your integration can receive redundant requests, use idempotency. A replay within 24 hours returns the stored response without consuming an extra credit.

Separate environments: do not put your cdns_live_* key in a CI job that runs 20 times per push. Create a dedicated cdns_test_* key and assign it to an appropriate plan (even the same plan, but tracked separately in the dashboard).

Overage billing

Overage is billed automatically after each monthly period closes. The amount is computed at the plan's rate (see the table above) and charged in a single transaction. In case of billing errors, the system retries automatically. If the issue persists, contact CaptainDNS support.

Next steps: rate limiting explains how to smooth your calls, and idempotency explains how to save credits on retries.