Abrechnung
Was eine Anfrage kostet und wie du es nachvollziehst.
Preise pro Endpunkt und Feature
Die API rechnet in Credits ab. Jede Anfrage kostet den Grundpreis ihres Endpunkts, dazu die Features, die Daten liefern, und gewählte Aufschläge. Die Preise sind in jedem Plan gleich. Der Plan entscheidet, welche Features du nutzen kannst.
| Endpunkt | Was | Credits |
|---|---|---|
| fetch-organization | Firmenprofil mit den Basisdaten | 5 |
| fetch-organization | Features, siehe nächste Tabelle | 1 bis 80 |
| fetch-organization | Aufschlag AI-Mode, auch ohne Treffer | +20 |
| fetch-organization | Aufschlag Echtzeit, bei jedem erfolgreichen Live-Abruf | +10 |
| fetch-person | Personenprofil, Webrecherche inklusive (ab Plus) | 15 |
| fetch-person |
Feature shareholdings, nur mit Daten
|
+5 |
| fetch-person |
Feature network (Pro, Max), nur mit Daten
|
+25 |
| search-organizations | Eine Seite Treffer, auch eine leere | 1 |
| fetch-document | Ein geliefertes Dokument | 15 |
| signals | Eine Seite Signals oder ein einzelnes Signal | 20 |
| signals |
Der Themenkatalog /v1/signals/catalog
|
kostenlos |
| account, auth | Konto, Guthaben, Nutzung, Schlüssel, Tokens und Webhook-Endpoints | kostenlos |
Die Features von fetch-organization fragst du einzeln an. Jedes kostet nur, wenn es Daten liefert:
| Feature | Inhalt | Credits | Plan |
|---|---|---|---|
| related_persons | Geschäftsführung | 2 | jedes Konto |
| shareholders | Gesellschafter (Beta) | 5 | jedes Konto |
| shareholders_deep | Tiefe Gesellschafter | 80 | Max |
| ubos | Wirtschaftlich Berechtigte (UBO, Beta) | 10 | jedes Konto |
| shareholdings | Beteiligungen (Beta) | 5 | jedes Konto |
| mergers_and_acquisitions | Fusionen & Übernahmen (M&A, Beta) | 20 | jedes Konto |
| network | Firmen-Netzwerk (Beta) | 25 | Pro, Max |
| publications | Historie: die Registerbekanntmachungen | 1 | jedes Konto |
| financial_kpi | Finanz-KPIs | 1 | jedes Konto |
| balance_sheet_accounts | Bilanz | 3 | jedes Konto |
| profit_and_loss_account | Gewinn- und Verlustrechnung (GuV) | 3 | jedes Konto |
| annual_financial_statements | Jahresabschlüsse (Markdown) | 5 | jedes Konto |
| annual_financial_statements__html | Jahresabschlüsse (HTML) | 5 | jedes Konto |
| insolvency_publications | Insolvenzbekanntmachungen | 5 | jedes Konto |
| news | Nachrichten | 10 | jedes Konto |
| website_content | Website-Inhalt · nur mit AI-Mode | kostenlos | jedes Konto |
Mit allen Features und beiden Aufschlägen kostet eine Anfrage an fetch-organization höchstens 215 Credits. Diesen Umfang gibt es mit Max.
Ein Monitor kostet pro Zeitraum von 30 Tagen einen festen Preis, abhängig vom Prüfrhythmus. Anlegen und die erste Bestandsaufnahme sind kostenlos.
| Prüfrhythmus | Credits pro 30 Tage |
|---|---|
| jeden Tag | 50 |
| alle 3 Tage | 40 |
| alle 7 Tage | 20 |
| alle 30 Tage | 10 |
| Jede weitere erfolgreiche Prüfung im Zeitraum | +2 |
Ein Rhythmus zwischen diesen Stufen kostet so viel wie die nächsthäufigere Stufe. Mehr dazu unter account/monitors.
Nur bezahlen, was Daten liefert
Ein Feature ohne Daten kostet nichts. Liefert es null oder eine leere Liste, zahlst du es nicht. Das gilt für jedes Feature, auch für insolvency_publications: Ohne Insolvenzbekanntmachungen ist es kostenlos.
Grundpreis und Aufschläge folgen eigenen Regeln. Den Grundpreis zahlst du für jedes gelieferte Firmenprofil. Der AI-Mode kostet auch ohne Treffer. Echtzeit kostet bei jedem erfolgreichen Live-Abruf, auch wenn sich im Register nichts geändert hat. Mehr unter Aufschläge.
Bei einigen Features kommt es auf bestimmte Inhalte an:
shareholdersundshareholders_deepkosten nur, wenn es aktuelle Einträge gibt. Eine reine Historie ist kostenlos.mergers_and_acquisitionskostet nur mit Transaktionen, Kontrollbeziehungen oder Rechtsnachfolgen.networkkostet nur mit mindestens einer Verbindung.newskostet, sobald die Liste mindestens einen Artikel enthält.
Ein Feature, das dein Plan nicht enthält, lässt fetch-organization weg und berechnet es nicht.
Bei Suche & Export, Dokumenten und Signals bezahlst du die Anfrage selbst: eine Seite Treffer, ein Dokument, eine Seite Signals. Auch eine Suche ohne Treffer und eine leere Seite Signals werden berechnet.
Eine gescheiterte oder abgelehnte Anfrage kostet nichts, siehe Fehler.
Aufschläge für AI-Mode und Echtzeit
fetch-organization kennt zwei Aufschläge, die du pro Anfrage zuschaltest.
AI-Mode (ai_search=on-default, +20 Credits) findet die Firma auch bei unscharfen Angaben und recherchiert im Web. Er wird berechnet, sobald die Recherche gelaufen ist, auch wenn sie keine Firma findet oder die Datenquelle einen Fehler meldet. Nur wenn die API die Anfrage mit 408 abbricht, entfällt er.
Echtzeit (realtime_mode=handelsregister-default, +10 Credits) holt die eingetragenen Personen live aus dem Handelsregister. Den Aufschlag berechnen wir, wenn der Live-Abruf gelingt, unabhängig davon, was er liefert. Dann steht in _realtime_mode.status der Wert success.
Steht dort ein anderer Wert, ist der Live-Abruf nicht gelungen. Du bekommst dann die gespeicherten Daten und zahlst den Rest der Anfrage, ohne Aufschlag für Echtzeit. Dauert die Anfrage zu lange, antwortet die API mit 408 und berechnet nichts.
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}
Kosten in der Antwort
Jede Antwort sagt, was sie gekostet hat. In JSON-Antworten steht das in meta, bei Dokumenten in Headern.
| Wo | Bedeutung |
|---|---|
| meta.request_credit_cost |
Was diese Anfrage gekostet hat. Bei Wiederholungen mit Idempotency-Key und fast allen Fehlern steht hier 0.
|
| meta.credits_remaining | Dein Guthaben nach der Anfrage. |
| X-Credits-Charged | signals und ein geliefertes Dokument: was die Anfrage gekostet hat, als Header. |
| X-Credits-Remaining | Ein geliefertes Dokument: dein Guthaben nach der Anfrage, als Header. |
1{2 "name": "Hetzner Online GmbH",3 "meta": {4 "request_credit_cost": 5,5 "credits_remaining": 1456 }7}
Ablehnungen bei der Anmeldung (401, 403) und über dem Limit (429) kommen meist ohne meta. Sie kosten nie etwas.
Jede Abbuchung findest du unter Konto › Nutzung und per API unter GET /v1/account/usage/transactions, siehe account.
Zu wenig Credits
Bevor die API eine Anfrage bearbeitet, prüft sie, ob dein Guthaben die höchstmöglichen Kosten deckt: Grundpreis, alle angefragten Features und die Aufschläge. Reicht es nicht, antwortet sie mit 402 und berechnet nichts.
In der Antwort steht dieser Höchstbetrag in meta.request_credit_cost, dein Guthaben in meta.credits_remaining. Berechnet wird später oft weniger, weil Features ohne Daten nichts kosten.
Ein Beispiel: Basisdaten mit AI-Mode und dem Feature ubos brauchen vorab 35 Credits. Liefert ubos keine Daten, kostet die Anfrage 25 Credits.
signals antwortet mit Problem Details und dem Code INSUFFICIENT_CREDITS.
Credit-Abo und Top-up Credits
Jedes neue Konto bekommt 150 Startcredits. Sie gelten 30 Tage.
Mit einem Credit-Abo (Plus, Pro, Max oder Enterprise) bekommst du jeden Monat Credits. Sie gelten bis zum Ende des Abrechnungszeitraums. Wechselst du den Plan, nimmst du offene Monats-Credits in den neuen Zeitraum mit. Ab Plus kannst du fetch-person nutzen, Pro und Max schalten zusätzliche Daten frei.
Top-up Credits kaufst du einmalig dazu. Ohne Credit-Abo gelten sie 30 Tage. Solange ein Credit-Abo läuft, verfallen weder Top-up Credits noch Startcredits.
Dein Guthaben und was wann verfällt, siehst du unter Konto › Credits und per API unter GET /v1/account/credits.
Alle Pläne und Preise stehen in der Preisübersicht.