account/monitors – Dokumentáció

Költségek és limitek

Költségek és limitek
Mi	Kredit
Monitor, ellenőrzés naponta, 30 napig	50
Monitor, ellenőrzés 3 naponta, 30 napig	40
Monitor, ellenőrzés 7 naponta, 30 napig	20
Monitor, ellenőrzés 30 naponta, 30 napig	10
Minden további sikeres ellenőrzés az időszakban	+2

Limit: percenként 30 kérés. Létrehozás, módosítás és törlés: percenként 10.

A monitor létrehozása és az első kiindulási állapot ingyenes. Egy 30 napos ciklust akkor számolunk fel, amikor a monitor aktívvá válik. Az ár az ellenőrzési időköztől függ, és lefedi az időköz által egy ciklusban ütemezett összes ellenőrzést.

Két lépcső közötti időköz annyiba kerül, mint a következő gyakoribb lépcső: a négynaponkénti annyiba kerül, mint a háromnaponkénti.

Plusz ellenőrzések főként akkor történnek, ha egy ciklus közepén lerövidíted az időközt. Minden sikeres plusz ellenőrzés a táblázatban szereplő összegbe kerül.

30 nap után a ciklus automatikusan megújul az akkor érvényes áron. A sikertelen ellenőrzések nem kerülnek semmibe. Szüneteltetéskor, archiváláskor vagy az időköz módosításakor semmit nem térítünk vissza.

Fiókonként egyszerre legfeljebb 50 monitor lehet, cégenként egy. 24 órán belül legfeljebb 50 monitort hozhatsz létre; az archiváltak is beleszámítanak.

Egy időköz árát ingyen megkapod a GET /v1/account/monitoring/pricing végponton, itt hétnaponkénti ellenőrzésre:

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitoring/pricing",
    headers={"x-api-key": "AZ_API_KULCSOD"},
    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": "AZ_API_KULCSOD" },
});
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 · Példaválasz: egy hétnaponként ellenőrző monitor ára

Hogyan működik egy monitor

Létrehozás. Megadod a céget, az ellenőrzési időközt és legalább egy ellenőrzött webhook-végpontot. A monitor initializing státusszal indul.
Kiindulási állapot. Az utolsó néhány nap jelzéseit ismertként rögzítjük. Ezeket nem kézbesítjük, így csak az azutáni újdonságokat kapod meg.
Aktiválás. Felszámoljuk a ciklust, a monitor active lesz, és azonnal először ellenőriz.
Ellenőrzés. Ezután a választott időközönként ellenőriz. Minden új jelzés monitoronként egy üzenetet vált ki a webhook-végpontjaidra.
Megújítás. Minden ciklus után automatikusan felszámoljuk a következőt, amíg az egyenleged fedezi.

Az ellenőrzési időköz 1 és 30 nap között van. Egy ellenőrzés pontos időpontja egy órán belül változhat. Minden ellenőrzés néhány napra visszatekint, így a későn közzétett bejegyzések is megérkeznek.

Egy monitor a csomagod Signals-témáit szállítja: minden fiókban ötöt, a Fizetésképtelenségeket a Pro, az Átalakulásokat és M&A-t a Max csomaggal. Egy webhook a data.signal mezőben ugyanazt a jelzést hordozza, mint a signals.

Státusz
Státusz	Jelentés
initializing	Létrehozva; a kiindulási állapot és az aktiválás folyamatban.
active	A választott időközönként ellenőriz.
paused_user	Te szüneteltetted.
paused_configuration	Már nincs csatlakoztatva aktív, ellenőrzött webhook-végpont.
paused_billing	Az egyenleged nem fedezi a ciklust vagy egy plusz ellenőrzést. Vagy az ár megváltozott, és a hozzájárulásodra vár.
error	Több egymást követő ellenőrzés sikertelen volt.
archived	Végleg befejezve. A monitort az azonosítója alapján még lekérheted, de a listában már nem jelenik meg.

Szüneteltetett monitoroknál és hibáknál a status_reason megmagyarázza az okát, például no_verified_endpoint vagy insufficient_cycle_floor.

Végpontok

Minden útvonal a /v1/account alatt van. Az API-kulcsoddal olvasol és írsz, az x-api-key headerben.

Metódus
Metódus	Útvonal	Cél
GET	`/v1/account/monitors`	Az összes monitor, a legújabbal kezdve, archiváltak nélkül.
POST	`/v1/account/monitors`	Monitor létrehozása.
GET	`/v1/account/monitors/{id}`	Egy monitor a ciklusával és a legutóbbi ellenőrzéseivel.
PATCH	`/v1/account/monitors/{id}`	Az ellenőrzési időköz módosítása.
POST	`/v1/account/monitors/{id}/pause`	Szüneteltetés.
POST	`/v1/account/monitors/{id}/resume`	Folytatás.
DELETE	`/v1/account/monitors/{id}`	Archiválás.
GET	`/v1/account/monitoring/pricing`	Egy időköz ára.

Idempotency-Key

Minden írási kéréshez kell az Idempotency-Key header, műveletenként egy egyedi érték, legjobb egy UUID. Nélküle az API 428-cal válaszol.

Ha egy kérést 24 órán belül ugyanazzal a kulccsal és ugyanazokkal az adatokkal megismételsz, a tárolt választ kapod vissza. Ez az Idempotency-Status: replayed headert hordozza. Így egy hálózati hiba nem hoz létre második monitort.

Ez a hibaválaszokra is érvényes. Ezért javítás utáni új kísérlethez használj új kulcsot. Ugyanaz a kulcs más adatokkal 409-et ad.

Legfeljebb 128 karakter engedélyezett: betűk, számjegyek és a . _ : - jelek. Az első karakter betű vagy számjegy. Más formátumú kulcs 400-at ad.

Monitor létrehozása

Szükséged van a cég entity_id-jára és legalább egy ellenőrzött webhook-végpontra, lásd account/webhook-endpoints.

curl -X POST "https://handelsregister.ai/api/v1/account/monitors" \
  -H "x-api-key: AZ_API_KULCSOD" \
  -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": "AZ_API_KULCSOD",
        "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": "AZ_API_KULCSOD",
    "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();

Paraméterek
Név	Típus	Leírás	Példa
Idempotency-KeyHeader	stringkötelező	Műveletenként egy egyedi érték, legjobb egy UUID. Lásd Idempotency-Key.Limitek: 1–128 karakter	`req-20260802-01`
entity_idBody	stringkötelező	A cég `entity_id`-ja a fetch-organization vagy a search-organizations válaszából.Limitek: 1–128 karakter	`94eb910fef13f94585c48c263fa446d4`
labelBody	stringopcionális	Egy név a monitornak.Limitek: legfeljebb 200 karakter	`Hetzner Online GmbH`
poll_interval_daysBody	integerkötelező	Ellenőrzési időköz napokban.Limitek: 1–30	`7`
endpoint_idsBody	string listakötelező	A webhook-végpontjaid azonosítói (`wep_…`). Mindegyiknek aktívnak és ellenőrzöttnek kell lennie.Limitek: 1–10 elem	`["wep_01m6b3j1g0cdz98hw8zdefbf52"]`

Az API 202-vel válaszol: a monitor létrejött, a kiindulási állapot és az aktiválás a háttérben fut. A meta.billing.charged_credits mutatja, hogy ezért semmit nem számoltunk fel.

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 · Példaválasz: egy új monitor, a példánkban a Hetzner Online GmbH-ra (Ansbach HRB 6089)

Az API-n keresztül a webhook-végpontokat a monitor létrehozásakor adod meg. További webhook-végpontot a Fiók › Monitoring alatt a „Cél összekapcsolása” lehetőséggel kapcsolsz hozzá, felár nélkül.

Monitorok listázása és módosítása

A GET /v1/account/monitors legfeljebb 100 monitort ad vissza a monitors alatt, a total mezővel. Az archiváltak nincsenek a listában.

A GET /v1/account/monitors/{id} az aktuális ciklust is mutatja a billing_cycle, a legutóbbi ellenőrzéseket a recent_runs alatt.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec",
    headers={"x-api-key": "AZ_API_KULCSOD"},
)
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": "AZ_API_KULCSOD" },
});
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 · Példaválasz: egy aktív, naponta ellenőrző monitor, ismét a Hetzner Online GmbH-ra

Egy monitor mezői
Mező	Jelentés
id	A monitor azonosítója, `mon_` előtaggal kezdődik.
entity_id	A figyelt cég.
poll_interval_days	Ellenőrzési időköz napokban.
status, status_reason	Státusz, lásd fent. A `status_reason` megadja az okát.
baseline_completed_at, activated_at, last_succeeded_at	A kiindulási állapot, az aktiválás és az utolsó sikeres ellenőrzés időpontjai.
next_poll_at	A következő ütemezett ellenőrzés, csak aktív monitoroknál.
billing_cycle	Az aktuális ciklus: kezdet, vég, ár, benne foglalt ellenőrzések és az eddig elvégzett ellenőrzések.
recent_runs	A legutóbbi ellenőrzések eredménnyel, elszámolással és az új jelzések számával az `events_new` mezőben.

A PATCH /v1/account/monitors/{id} módosítja az ellenőrzési időközt. A következő ellenőrzés ezután az új időköz szerint következik, a módosítástól számítva.

Az aktuális ciklus megtartja az árát és a benne foglalt ellenőrzéseket. Az új ár a következő ciklustól érvényes. Egy rövidebb időköz plusz ellenőrzéseket válthat ki az aktuális ciklusban.

curl -X PATCH "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz" \
  -H "x-api-key: AZ_API_KULCSOD" \
  -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": "AZ_API_KULCSOD",
        "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": "AZ_API_KULCSOD",
    "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 · Példaválasz: az időköz 30 napra módosítva

Szüneteltetés, folytatás, archiválás

A POST …/{id}/pause leállít egy aktív monitort. A kifizetett ciklus kifut, és semmit nem térítünk vissza.

A POST …/{id}/resume folytat egy szüneteltetett vagy hibás monitort. Újra ellenőrizzük a webhook-végpontokat, az egyenleget és az árat.

Az aktuális kifizetett cikluson belül a folytatás nem kerül semmibe. Ha a ciklus lejárt, most új ciklus indul az aktuális áron. A meta.request_credit_cost mutatja az összeget.

Ha például hiányzik egy ellenőrzött webhook-végpont, az API ennek ellenére 200-zal válaszol, de meta.activated: false értékkel. A monitor státusza és a status_reason megadja az okát.

Ha az ár megváltozott, egy aktív monitor a ciklus végén pricing_consent_required okkal leáll. A resume hívással elfogadod az új árat.

A DELETE …/{id} véglegesen archiválja a monitort. Ez végleges, és semmit nem térít vissza.

curl -X POST "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume" \
  -H "x-api-key: AZ_API_KULCSOD" \
  -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": "AZ_API_KULCSOD",
        "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": "AZ_API_KULCSOD",
    "Idempotency-Key": crypto.randomUUID(),
  },
});
const data = await response.json();

Ha letiltasz vagy archiválsz egy webhook-végpontot, minden más webhook-végpont nélküli monitor paused_configuration okkal szünetel. Miután engedélyezted a webhook-végpontot, folytasd a monitort a resume hívással.

Hibák

A hibák felépítése {"error": "…", "meta": {"message": "…"}}. A programodban az error értékét ellenőrizd. A meta.message szövege angol, és változhat. A hibák nem kerülnek semmibe.

Hibák
Státusz	Ok	Mit tehetsz
400	Az `api_key` az URL-ben van.	Küldd a kulcsot az `x-api-key` headerben.
400	Az `Idempotency-Key` formátuma érvénytelen.	Javítsd a formátumot, például használj UUID-t.
401	Nincs API-kulcs vagy token, vagy érvénytelen.	Küldd a kulcsot az `x-api-key` headerben.
403	A bearer tokenből hiányzik az `account:read` jogosultság.	Használd az API-kulcsot vagy egy `account:read` jogosultságú tokent.
403	A fiókod e-mail-címe még nincs megerősítve, vagy a fiók zárolva van.	Nyisd meg a megerősítő e-mailben lévő linket. Ha a fiók zárolva van, a support segít.
403	A bearer tokenből hiányzik a `monitoring:manage` jogosultság.	Használd az API-kulcsot vagy az admin tokent.
404	Nincs ilyen azonosítójú monitor a fiókodban.	Ellenőrizd az azonosítót.
409	Ehhez a céghez már létezik monitor (`duplicate_monitor`).	Használd a meglévő monitort, vagy előbb archiváld.
409	Az `Idempotency-Key` kulcsot már más adatokkal használták, 24 óránál régebbi, vagy még feldolgozás alatt áll.	Használj új kulcsot, vagy várj egy kicsit.
422	Egy érték érvénytelen: `invalid_subject`, `invalid_interval`, `endpoint_required`, `monitor_limit` vagy `not_resumable`.	Javítsd az értéket.
428	Hiányzik az `Idempotency-Key` header.	Küldd el a headert.
429	Túl sok kérés.	Próbáld újra a `Retry-After` után.
429	`creation_rate_limited`: túl sok új monitor 24 órán belül.	Próbáld újra a `Retry-After` után.
503	A Monitoring átmenetileg nem érhető el.	Próbáld újra kicsit később.

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 · Második monitor ugyanarra a cégre