Billing
What a request costs and how you can trace it.
Prices per endpoint and feature
The API bills in credits. Each request costs its endpoint's base price, plus the features that return data and any surcharges you choose. Prices are the same in every plan. Your plan decides which features you can use.
| Endpoint | What | Credits |
|---|---|---|
| fetch-organization | Company profile with the basic data | 5 |
| fetch-organization | Features, see the next table | 1 to 80 |
| fetch-organization | AI Mode surcharge, even without a match | +20 |
| fetch-organization | Realtime surcharge, for every successful live fetch | +10 |
| fetch-person | Person profile, web research included (from Plus) | 15 |
| fetch-person |
Feature shareholdings, only when it returns data
|
+5 |
| fetch-person |
Feature network (Pro, Max), only when it returns data
|
+25 |
| search-organizations | One page of results, even an empty one | 1 |
| fetch-document | One delivered document | 15 |
| signals | One page of Signals or a single signal | 20 |
| signals |
The topic catalog /v1/signals/catalog
|
free |
| account, auth | Account, balance, usage, keys, tokens and webhook endpoints | free |
You request the features of fetch-organization one by one. Each costs only when it returns data:
| Feature | Content | Credits | Plan |
|---|---|---|---|
| related_persons | Management | 2 | every account |
| shareholders | Shareholders (Beta) | 5 | every account |
| shareholders_deep | Deep Shareholders | 80 | Max |
| ubos | Beneficial owners (UBO, Beta) | 10 | every account |
| shareholdings | Shareholdings (Beta) | 5 | every account |
| mergers_and_acquisitions | Mergers & Acquisitions (M&A, Beta) | 20 | every account |
| network | Company network (Beta) | 25 | Pro, Max |
| publications | History: the register notices | 1 | every account |
| financial_kpi | Financial KPIs | 1 | every account |
| balance_sheet_accounts | Balance sheet | 3 | every account |
| profit_and_loss_account | Profit and loss statement (P&L) | 3 | every account |
| annual_financial_statements | Annual statements (Markdown) | 5 | every account |
| annual_financial_statements__html | Annual statements (HTML) | 5 | every account |
| insolvency_publications | Insolvency notices | 5 | every account |
| news | News | 10 | every account |
| website_content | Website content · only with AI Mode | free | every account |
With all features and both surcharges, a request to fetch-organization costs at most 215 credits. This scope comes with Max.
A monitor costs a fixed price per period of 30 days, depending on the check interval. Creating it and the first baseline are free.
| Check interval | Credits per 30 days |
|---|---|
| every day | 50 |
| every 3 days | 40 |
| every 7 days | 20 |
| every 30 days | 10 |
| Each further successful check in the period | +2 |
An interval between these steps costs as much as the next more frequent step. More under account/monitors.
Pay only for what returns data
A feature without data costs nothing. If it returns null or an empty list, you don't pay for it. This applies to every feature, including insolvency_publications: without insolvency notices it is free.
The base price and the surcharges follow their own rules. You pay the base price for every delivered company profile. AI Mode costs even without a match. Realtime costs for every successful live fetch, even if nothing has changed in the register. More under Surcharges.
For some features, specific content matters:
shareholdersandshareholders_deepcost only when there are current entries. A history alone is free.mergers_and_acquisitionscosts only with transactions, control relationships or legal successions.networkcosts only with at least one connection.newscosts as soon as the list contains at least one article.
fetch-organization leaves out a feature your plan does not include and does not bill it.
With Search & Export, documents and Signals, you pay for the request itself: one page of results, one document, one page of Signals. A search without results and an empty page of Signals are billed too.
A failed or rejected request costs nothing, see Errors.
Surcharges for AI Mode and Realtime
fetch-organization has two surcharges that you switch on per request.
AI Mode (ai_search=on-default, +20 credits) finds the company even from vague input and researches on the web. It is billed as soon as the research has run, even if it finds no company or the data source reports an error. Only when the API aborts the request with 408 is it not billed.
Realtime (realtime_mode=handelsregister-default, +10 credits) fetches the registered people live from the Handelsregister (commercial register). We bill the surcharge when the live fetch succeeds, regardless of what it returns. Then _realtime_mode.status has the value success.
Any other value there means the live fetch failed. You then get the stored data and pay for the rest of the request, without the Realtime surcharge. If the request takes too long, the API answers with 408 and bills nothing.
1{2 "name": "Hetzner Online GmbH",3 "_realtime_mode": {4 "mode": "handelsregister-default",5 "status": "success"6 },7 "meta": {8 "request_credit_cost": 15,9 "credits_remaining": 14510 }11}
Costs in the response
Every response tells you what it cost. In JSON responses this is in meta, for documents in headers.
| Where | Meaning |
|---|---|
| meta.request_credit_cost |
What this request cost. For retries with an idempotency key and almost all errors, this is 0.
|
| meta.credits_remaining | Your balance after the request. |
| X-Credits-Charged | signals and a delivered document: what the request cost, as a header. |
| X-Credits-Remaining | A delivered document: your balance after the request, as a header. |
1{2 "name": "Hetzner Online GmbH",3 "meta": {4 "request_credit_cost": 5,5 "credits_remaining": 1456 }7}
Rejections at authentication (401, 403) and over the limit (429) usually come without meta. They never cost anything.
You find every charge under Account › Usage and via the API at GET /v1/account/usage/transactions, see account.
Not enough credits
Before the API processes a request, it checks whether your balance covers the highest possible cost: base price, all requested features and the surcharges. If it doesn't, the API answers with 402 and bills nothing.
The response shows this maximum in meta.request_credit_cost and your balance in meta.credits_remaining. The amount billed later is often lower, because features without data cost nothing.
An example: basic data with AI Mode and the feature ubos need 35 credits up front. If ubos returns no data, the request costs 25 credits.
signals answers with Problem Details and the code INSUFFICIENT_CREDITS.
Credit subscription and top-up credits
Every new account gets 150 start credits. They are valid for 30 days.
With a credit subscription (Plus, Pro, Max or Enterprise), you get credits every month. They are valid until the end of the billing period. If you change your plan, you take unused monthly credits into the new period. From Plus on you can use fetch-person; Pro and Max unlock additional data.
You buy top-up credits once, on top. Without a credit subscription, they are valid for 30 days. As long as a credit subscription is running, neither top-up credits nor start credits expire.
You see your balance and what expires when under Account › Credits and via the API at GET /v1/account/credits.
All plans and prices are on the pricing page.