account/monitors – Dokumentace

Náklady a limity

Náklady a limity
Co	Kredity
Monitor kontrolovaný každý den, po dobu 30 dní	50
Monitor kontrolovaný každé 3 dny, po dobu 30 dní	40
Monitor kontrolovaný každých 7 dní, po dobu 30 dní	20
Monitor kontrolovaný každých 30 dní, po dobu 30 dní	10
Každá další úspěšná kontrola v období	+2

Limit: 30 požadavků za minutu. Vytvoření, úprava a smazání: 10 za minutu.

Vytvoření monitoru a první výchozí stav jsou zdarma. Cyklus 30 dní se účtuje, jakmile se monitor aktivuje. Cena závisí na intervalu kontrol a pokrývá všechny kontroly, které interval v rámci jednoho cyklu naplánuje.

Interval mezi dvěma stupni stojí tolik jako nejbližší častější stupeň: každé čtyři dny stojí tolik jako každé tři dny.

Kontroly navíc vznikají hlavně tehdy, když interval zkrátíš uprostřed cyklu. Každá úspěšná kontrola navíc stojí částku z tabulky.

Po 30 dnech se cyklus automaticky obnoví za tehdy platnou cenu. Neúspěšné kontroly nic nestojí. Při pozastavení, archivaci nebo změně intervalu nic nevracíme.

Každý účet může mít současně až 50 monitorů, jeden na firmu. Během 24 hodin můžeš vytvořit až 50 monitorů; počítají se i archivované.

Cenu intervalu zjistíš zdarma přes GET /v1/account/monitoring/pricing, zde pro kontrolu každých sedm dní:

curl -G "https://handelsregister.ai/api/v1/account/monitoring/pricing" \
  -H "x-api-key: TVUJ_API_KLIC" \
  --data-urlencode 'poll_interval_days=7'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitoring/pricing",
    headers={"x-api-key": "TVUJ_API_KLIC"},
    params={
        "poll_interval_days": "7",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/account/monitoring/pricing");
url.searchParams.append("poll_interval_days", "7");

const response = await fetch(url, {
  headers: { "x-api-key": "TVUJ_API_KLIC" },
});
const data = await response.json();

1{2  "pricing": {3    "policy_version": "2026-08.v2",4    "credits_per_run": 2,5    "cycle_minimum_credits": 20,6    "included_runs": 5,7    "cycle_days": 30,8    "estimated_runs": 5,9    "estimated_credits": 2010  },11  "entitled": true,12  "meta": {13    "request_credit_cost": 0,14    "credits_remaining": 14515  }16}

200 · Ukázková odpověď: cena monitoru s kontrolou každých 7 dní

Jak monitor funguje

Vytvoření. Uvedeš firmu, interval kontrol a alespoň jeden ověřený webhook endpoint. Monitor začíná se stavem initializing.
Výchozí stav. Signály posledních několika dní zaznamenáme jako známé. Nedoručují se, takže dostáváš jen to, co je potom nové.
Aktivace. Zaúčtujeme cyklus, monitor přejde do active a hned poprvé zkontroluje.
Kontrola. Potom kontroluje ve zvoleném intervalu. Každý nový signál vyvolá jednu zprávu na monitor na tvé webhook endpointy.
Obnovení. Po každém cyklu se automaticky zaúčtuje další, pokud to tvůj zůstatek pokryje.

Interval kontrol je mezi 1 a 30 dny. Přesný čas kontroly se může v rámci hodiny lišit. Každá kontrola se dívá několik dní zpět, takže dorazí i pozdě zveřejněné zápisy.

Monitor doručuje témata Signals tvého tarifu: pět v každém účtu, Insolvence s tarifem Pro, Přeměny a M&A s tarifem Max. Webhook nese v poli data.signal stejný signál jako signals.

Stav
Stav	Význam
initializing	Vytvořen; výchozí stav a aktivace probíhají.
active	Kontroluje ve zvoleném intervalu.
paused_user	Pozastaven tebou.
paused_configuration	Už není připojen žádný aktivní, ověřený webhook endpoint.
paused_billing	Tvůj zůstatek nepokryje cyklus nebo kontrolu navíc. Nebo se změnila cena a čeká na tvůj souhlas.
error	Několik kontrol po sobě selhalo.
archived	Ukončen natrvalo. Monitor si můžeš dál přečíst podle ID, ale v seznamu se už neobjevuje.

U pozastavených monitorů a chyb vysvětluje status_reason proč, například no_verified_endpoint nebo insufficient_cycle_floor.

Endpointy

Všechny cesty jsou pod /v1/account. Čteš i zapisuješ se svým API klíčem v headeru x-api-key.

Metoda
Metoda	Cesta	Účel
GET	`/v1/account/monitors`	Všechny monitory, nejnovější první, bez archivovaných.
POST	`/v1/account/monitors`	Vytvořit monitor.
GET	`/v1/account/monitors/{id}`	Jeden monitor s cyklem a posledními kontrolami.
PATCH	`/v1/account/monitors/{id}`	Změnit interval kontrol.
POST	`/v1/account/monitors/{id}/pause`	Pozastavit.
POST	`/v1/account/monitors/{id}/resume`	Obnovit.
DELETE	`/v1/account/monitors/{id}`	Archivovat.
GET	`/v1/account/monitoring/pricing`	Cena intervalu.

Idempotency-Key

Každý zápisový požadavek potřebuje header Idempotency-Key, jednoznačnou hodnotu pro každou operaci, ideálně UUID. Bez něj API odpoví 428.

Pokud požadavek zopakuješ se stejným klíčem a stejnými daty do 24 hodin, dostaneš zpět uloženou odpověď. Nese header Idempotency-Status: replayed. Chyba sítě tak nevytvoří druhý monitor.

To platí i pro chybové odpovědi. Pro nový pokus po opravě proto použij nový klíč. Stejný klíč s jinými daty vrátí 409.

Povoleno je až 128 znaků: písmena, číslice a . _ : -. Prvním znakem je písmeno nebo číslice. Klíč v jiném formátu vrátí 400.

Vytvořit monitor

Potřebuješ entity_id firmy a alespoň jeden ověřený webhook endpoint, viz account/webhook-endpoints.

curl -X POST "https://handelsregister.ai/api/v1/account/monitors" \
  -H "x-api-key: TVUJ_API_KLIC" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "94eb910fef13f94585c48c263fa446d4",
    "label": "Hetzner Online GmbH",
    "poll_interval_days": 7,
    "endpoint_ids": [
        "wep_01m6b3j1g0cdz98hw8zdefbf52"
    ]
}'

import uuid
import requests

response = requests.post(
    "https://handelsregister.ai/api/v1/account/monitors",
    headers={
        "x-api-key": "TVUJ_API_KLIC",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "entity_id": "94eb910fef13f94585c48c263fa446d4",
        "label": "Hetzner Online GmbH",
        "poll_interval_days": 7,
        "endpoint_ids": [
            "wep_01m6b3j1g0cdz98hw8zdefbf52"
        ]
    },
)
data = response.json()

const response = await fetch("https://handelsregister.ai/api/v1/account/monitors", {
  method: "POST",
  headers: {
    "x-api-key": "TVUJ_API_KLIC",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "entity_id": "94eb910fef13f94585c48c263fa446d4",
      "label": "Hetzner Online GmbH",
      "poll_interval_days": 7,
      "endpoint_ids": [
          "wep_01m6b3j1g0cdz98hw8zdefbf52"
      ]
  }),
});
const data = await response.json();

Parametry
Název	Typ	Popis	Příklad
Idempotency-KeyHeader	řetězecpovinný	Jednoznačná hodnota pro každou operaci, ideálně UUID. Viz Idempotency-Key.Limity: 1 až 128 znaků	`req-20260802-01`
entity_idBody	řetězecpovinný	`entity_id` firmy z fetch-organization nebo search-organizations.Limity: 1 až 128 znaků	`94eb910fef13f94585c48c263fa446d4`
labelBody	řetězecvolitelný	Název monitoru.Limity: nejvýše 200 znaků	`Hetzner Online GmbH`
poll_interval_daysBody	celé číslopovinný	Interval kontrol ve dnech.Limity: 1 až 30	`7`
endpoint_idsBody	seznam stringpovinný	ID tvých webhook endpointů (`wep_…`). Každý musí být aktivní a ověřený.Limity: 1 až 10 položek	`["wep_01m6b3j1g0cdz98hw8zdefbf52"]`

API odpoví 202: monitor je vytvořen a výchozí stav a aktivace běží na pozadí. meta.billing.charged_credits ukazuje, že se za to nic neúčtovalo.

1{2  "monitor": {3    "id": "mon_01m6b3m7945dn7cyvexzv41kjz",4    "type": "organization.signals",5    "entity_id": "94eb910fef13f94585c48c263fa446d4",6    "label": "Hetzner Online GmbH",7    "poll_interval_days": 7,8    "status": "initializing",9    "status_reason": null,10    "pricing_policy_version": "2026-08.v2",11    "baseline_completed_at": null,12    "activated_at": null,13    "last_succeeded_at": null,14    "next_poll_at": null,15    "created_at": "2026-11-01T08:29:13+00:00"16  },17  "meta": {18    "message": "Monitor created; the free baseline is queued and this request charged 0 credits. The cycle price is charged only when activation succeeds.",19    "baseline_queued": true,20    "billing": {21      "charged_credits": 0,22      "new_cycle": false,23      "floor_transaction_id": null24    },25    "request_credit_cost": 0,26    "credits_remaining": 14527  }28}

202 · Ukázková odpověď: nový monitor, v našem příkladu pro Hetzner Online GmbH, Ansbach HRB 6089

Přes API nastavuješ webhook endpointy při vytváření monitoru. Další webhook endpoint připojíš v Účet › Monitoring pomocí „Propojit cíl“, bez příplatku.

Vypsat a upravit monitory

GET /v1/account/monitors vrátí až 100 monitorů v monitors, s total. Archivované v seznamu nejsou.

GET /v1/account/monitors/{id} ukazuje navíc aktuální cyklus v billing_cycle a poslední kontroly v recent_runs.

curl -G "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec" \
  -H "x-api-key: TVUJ_API_KLIC"

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec",
    headers={"x-api-key": "TVUJ_API_KLIC"},
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec");

const response = await fetch(url, {
  headers: { "x-api-key": "TVUJ_API_KLIC" },
});
const data = await response.json();

1{2  "monitor": {3    "id": "mon_01m65pn3vm11sjjp1j076cbvec",4    "type": "organization.signals",5    "entity_id": "94eb910fef13f94585c48c263fa446d4",6    "label": "Hetzner Online GmbH",7    "poll_interval_days": 1,8    "status": "active",9    "status_reason": null,10    "pricing_policy_version": "2026-08.v2",11    "baseline_completed_at": "2026-10-30T06:06:28+00:00",12    "activated_at": "2026-10-30T06:06:28+00:00",13    "last_succeeded_at": "2026-10-30T06:06:53+00:00",14    "next_poll_at": "2026-10-31T06:19:12+00:00",15    "created_at": "2026-10-30T06:06:18+00:00"16  },17  "billing_cycle": {18    "starts_at": "2026-10-30T06:06:28+00:00",19    "ends_at": "2026-11-29T06:06:28+00:00",20    "floor_credits": 50,21    "credits_per_run": 2,22    "included_runs": 30,23    "successful_runs": 1,24    "extra_credits_settled": 0,25    "pricing_policy_version": "2026-08.v2"26  },27  "recent_runs": [28    {29      "due_slot_at": "2026-10-30T06:06:28+00:00",30      "kind": "activation_catchup",31      "status": "succeeded",32      "charge_state": "covered",33      "charge_credits": 0,34      "events_new": 0,35      "finished_at": "2026-10-30T06:06:55+00:00"36    }37  ],38  "meta": {39    "request_credit_cost": 0,40    "credits_remaining": 14541  }42}

200 · Ukázková odpověď: aktivní monitor s denní kontrolou, opět pro Hetzner Online GmbH

Pole monitoru
Pole	Význam
id	ID monitoru, začíná na `mon_`.
entity_id	Sledovaná firma.
poll_interval_days	Interval kontrol ve dnech.
status, status_reason	Stav, viz výše. `status_reason` uvádí důvod.
baseline_completed_at, activated_at, last_succeeded_at	Časy výchozího stavu, aktivace a poslední úspěšné kontroly.
next_poll_at	Další plánovaná kontrola, jen u aktivních monitorů.
billing_cycle	Aktuální cyklus: začátek, konec, cena, zahrnuté kontroly a dosud provedené kontroly.
recent_runs	Poslední kontroly s výsledkem, účtováním a počtem nových signálů v `events_new`.

PATCH /v1/account/monitors/{id} změní interval kontrol. Další kontrola pak následuje v novém intervalu, počítáno od změny.

Aktuální cyklus si ponechá svou cenu a zahrnuté kontroly. Nová cena platí od dalšího cyklu. Kratší interval může v aktuálním cyklu vyvolat kontroly navíc.

curl -X PATCH "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz" \
  -H "x-api-key: TVUJ_API_KLIC" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "poll_interval_days": 30
}'

import uuid
import requests

response = requests.patch(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz",
    headers={
        "x-api-key": "TVUJ_API_KLIC",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "poll_interval_days": 30
    },
)
data = response.json()

const response = await fetch("https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz", {
  method: "PATCH",
  headers: {
    "x-api-key": "TVUJ_API_KLIC",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "poll_interval_days": 30
  }),
});
const data = await response.json();

1{2  "monitor": {3    "id": "mon_01m6b3m7945dn7cyvexzv41kjz",4    "type": "organization.signals",5    "entity_id": "94eb910fef13f94585c48c263fa446d4",6    "label": "Hetzner Online GmbH",7    "poll_interval_days": 30,8    "status": "initializing",9    "status_reason": null,10    "pricing_policy_version": "2026-08.v2",11    "baseline_completed_at": null,12    "activated_at": null,13    "last_succeeded_at": null,14    "next_poll_at": null,15    "created_at": "2026-11-01T08:29:13+00:00"16  },17  "meta": {18    "request_credit_cost": 0,19    "credits_remaining": 14520  }21}

200 · Ukázková odpověď: interval změněn na 30 dní

Pozastavit, obnovit, archivovat

POST …/{id}/pause zastaví aktivní monitor. Zaplacený cyklus doběhne a nic se nevrací.

POST …/{id}/resume obnoví pozastavený monitor nebo monitor s chybou. Znovu zkontrolujeme webhook endpointy, zůstatek a cenu.

V rámci aktuálního zaplaceného cyklu obnovení nic nestojí. Pokud cyklus vypršel, začne teď nový cyklus za aktuální cenu. meta.request_credit_cost ukazuje částku.

Pokud například chybí ověřený webhook endpoint, API přesto odpoví 200, ale s meta.activated: false. Stav monitoru a status_reason uvádějí důvod.

Pokud se cena změnila, aktivní monitor se na konci cyklu zastaví s pricing_consent_required. Pomocí resume s novou cenou souhlasíš.

DELETE …/{id} monitor natrvalo archivuje. Je to konečné a nic se nevrací.

curl -X POST "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume" \
  -H "x-api-key: TVUJ_API_KLIC" \
  -H "Idempotency-Key: $(uuidgen)"

import uuid
import requests

response = requests.post(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume",
    headers={
        "x-api-key": "TVUJ_API_KLIC",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
data = response.json()

const response = await fetch("https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume", {
  method: "POST",
  headers: {
    "x-api-key": "TVUJ_API_KLIC",
    "Idempotency-Key": crypto.randomUUID(),
  },
});
const data = await response.json();

Pokud webhook endpoint vypneš nebo archivuješ, všechny monitory bez dalšího webhook endpointu se pozastaví s paused_configuration. Po zapnutí webhook endpointu obnov monitor pomocí resume.

Chyby

Chyby mají strukturu {"error": "…", "meta": {"message": "…"}}. Ve svém programu kontroluj hodnotu error. Text v meta.message je anglicky a může se změnit. Chyby nic nestojí.

Chyby
Stav	Příčina	Co můžeš udělat
400	`api_key` je v URL.	Posílej klíč v headeru `x-api-key`.
400	`Idempotency-Key` má neplatný formát.	Oprav formát, například použij UUID.
401	Žádný nebo neplatný API klíč či token.	Posílej klíč v headeru `x-api-key`.
403	Bearer tokenu chybí oprávnění `account:read`.	Použij API klíč nebo token s `account:read`.
403	E-mailová adresa tvého účtu ještě není potvrzená, nebo je účet zablokovaný.	Otevři odkaz z potvrzovacího e-mailu. Pokud je účet zablokovaný, pomůže ti podpora.
403	Bearer tokenu chybí oprávnění `monitoring:manage`.	Použij API klíč nebo admin token.
404	V tvém účtu není monitor s tímto ID.	Zkontroluj ID.
409	Pro tuto firmu už monitor existuje (`duplicate_monitor`).	Použij existující monitor nebo ho nejdřív archivuj.
409	`Idempotency-Key` už byl použit s jinými daty, je starší než 24 hodin, nebo se ještě zpracovává.	Použij nový klíč nebo chvíli počkej.
422	Hodnota je neplatná: `invalid_subject`, `invalid_interval`, `endpoint_required`, `monitor_limit` nebo `not_resumable`.	Oprav hodnotu.
428	Chybí header `Idempotency-Key`.	Pošli header.
429	Příliš mnoho požadavků.	Zkus to znovu po `Retry-After`.
429	`creation_rate_limited`: příliš mnoho nových monitorů během 24 hodin.	Zkus to znovu po `Retry-After`.
503	Monitoring je dočasně nedostupný.	Zkus to o něco později.

1{2  "error": "duplicate_monitor",3  "meta": {4    "message": "You already have a monitor for this company.",5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}

409 · Druhý monitor pro stejnou firmu