How credits and success billing work

Each product has a fixed price in credits per unit, read from the live catalog. For example, an IP lookup is 1 credit and a domain age lookup is 2. The credits and billing page lists every product with its price and unit.

Most products use success billing: you are charged only when the lookup finds something. A few use per-call billing, where every completed lookup is charged whether it found something or not. Today the per-call product is Link Safety Check.

The engine handles a request in a fixed order, and the order explains most of the table below.

1. It checks the input against the product schema. A bad input is refused before anything else happens.
2. It checks your account cache. A fresh stored answer for the same product and the same normalized input is returned right away.
3. It checks that your account has fewer than 16 lookups running at once. Past that, the request is refused.
4. It reserves the product price from your available balance. This is a hold, not a charge. If the balance cannot cover it, the request stops here and the data source is never called.
5. It runs the lookup under the product time limit.
6. It settles. A found result turns the hold into a charge. A result that was not found releases the hold under success billing and charges it under per-call billing. Errors always release it.

The hold is set to outlast the time limit by a safety margin. If a hold ever expired before settlement, the answer would still be returned and would not be charged. Credits held by lookups still in progress show as reserved in your balance and come back if those lookups find nothing.

Every row below follows from the engine order above. Charged means credits taken from your balance, and Stored means the answer is kept in your cache for the window in the next section.

On the success-billing rows, found: false is a normal answer with HTTP 200, not an error. It carries credits_charged: 0 and a reason. Branch on found, not on the status code.

Results are cached per account, and both found and not found answers are stored. A repeat of the same lookup inside the window returns the stored result with cache_hit: true and charges nothing. Another account that runs the same lookup pays for its own first one. Inputs are normalized before the cache key is built, so letter case or surrounding spaces do not make a new lookup. The longest window is 7 days.

Two identical requests that are in flight together are handled safely: the first to settle is charged and stored, and the second is returned from that stored entry without a second charge. The cache object in each response shows cached_at and expires_at, so you can see when a stored answer ages out.

Each lookup response carries credits_charged and credits_remaining, also sent as the X-Credits-Charged and X-Credits-Remaining headers. A call to GET /v1/account returns your granted, spent, reserved and available credits and never costs anything.

Here is a lookup whose cost depends on the result. A registered domain finds data and is charged. An unregistered domain returns found: false and is free, because domain age uses success billing.

1curl -X POST https://YOUR_API_HOST/v1/domain-age \
2  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"domain":"example.com"}'

• Do not retry a found: false result. It returns the same answer, free, until the window ends.
• Cache results on your side if you need them for longer than the window.
• Check the unit column on the credits and billing page: it says what one charge covers, such as one domain or one VIN.

To see these rules on your own data, run the example above with a key and then read the response headers. The quickstart covers creating the key, and the domain age product page lists the fields in the result.