account/monitors – Dokumentaatio

Kustannukset ja rajat

Kustannukset ja rajat
Mitä	Krediitit
Monitori tarkistetaan joka päivä, 30 päivän ajan	50
Monitori tarkistetaan 3 päivän välein, 30 päivän ajan	40
Monitori tarkistetaan 7 päivän välein, 30 päivän ajan	20
Monitori tarkistetaan 30 päivän välein, 30 päivän ajan	10
Jokainen jakson lisäksi onnistunut tarkistus	+2

Raja: 30 pyyntöä minuutissa. Luonti, muutos ja poisto: 10 minuutissa.

Monitorin luonti ja ensimmäinen lähtötilanne ovat maksuttomia. 30 päivän jakso veloitetaan heti, kun monitori aktivoituu. Hinta riippuu tarkistusvälistä ja kattaa kaikki välin mukaiset tarkistukset yhden jakson aikana.

Kahden portaan välissä oleva väli maksaa yhtä paljon kuin seuraava tiheämpi porras: neljän päivän välein maksaa yhtä paljon kuin kolmen päivän välein.

Lisätarkistuksia tulee lähinnä, kun lyhennät väliä kesken jakson. Jokainen onnistunut lisätarkistus maksaa taulukon mukaisen summan.

30 päivän jälkeen jakso uusiutuu automaattisesti silloin voimassa olevaan hintaan. Epäonnistuneet tarkistukset eivät maksa mitään. Kun keskeytät, arkistoit tai muutat väliä, emme hyvitä mitään.

Jokaisella tilillä voi olla samanaikaisesti enintään 50 monitoria, yksi yritystä kohden. 24 tunnin sisällä voit luoda enintään 50 monitoria; myös arkistoidut lasketaan.

Välin hinnan saat maksutta pyynnöllä GET /v1/account/monitoring/pricing, tässä tarkistukselle seitsemän päivän välein:

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitoring/pricing",
    headers={"x-api-key": "SINUN_API_AVAIMESI"},
    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": "SINUN_API_AVAIMESI" },
});
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 · Esimerkkivastaus: monitorin hinta tarkistuksella 7 päivän välein

Miten monitori toimii

Luonti. Annat yrityksen, tarkistusvälin ja vähintään yhden vahvistetun webhook-päätepisteen. Monitori alkaa tilassa initializing.
Lähtötilanne. Kirjaamme viimeisten päivien signaalit tunnetuiksi. Niitä ei toimiteta, joten saat vain sen jälkeen uudet.
Aktivointi. Veloitamme jakson, monitori muuttuu tilaan active ja tarkistaa ensimmäisen kerran heti.
Tarkistus. Sen jälkeen se tarkistaa valitulla välillä. Jokainen uusi signaali laukaisee yhden viestin monitoria kohden webhook-päätepisteisiisi.
Uusiminen. Jokaisen jakson jälkeen seuraava veloitetaan automaattisesti, kunhan saldosi riittää.

Tarkistusväli on 1–30 päivää. Tarkistuksen tarkka ajankohta voi vaihdella tunnin sisällä. Jokainen tarkistus katsoo muutaman päivän taaksepäin, joten myöhään julkaistut merkinnät tulevat silti perille.

Monitori toimittaa tilauksesi Signals-aiheet: viisi jokaisella tilillä, Maksukyvyttömyydet Prolla, Rakennejärjestelyt & M&A Maxilla. Webhook kuljettaa saman signaalin kentässä data.signal kuin signals.

Tila
Tila	Merkitys
initializing	Luotu; lähtötilanne ja aktivointi ovat käynnissä.
active	Tarkistaa valitulla välillä.
paused_user	Sinun keskeyttämäsi.
paused_configuration	Aktiivista, vahvistettua webhook-päätepistettä ei ole enää yhdistetty.
paused_billing	Saldosi ei riitä jaksoon tai lisätarkistukseen. Tai hinta on muuttunut ja odottaa suostumustasi.
error	Useita peräkkäisiä tarkistuksia on epäonnistunut.
archived	Päättynyt lopullisesti. Voit yhä lukea monitorin sen tunnisteella, mutta se ei enää näy listassa.

Keskeytetyillä monitoreilla ja virheissä status_reason kertoo syyn, esimerkiksi no_verified_endpoint tai insufficient_cycle_floor.

Päätepisteet

Kaikki polut ovat polun /v1/account alla. Luet ja kirjoitat API-avaimellasi headerissa x-api-key.

Metodi
Metodi	Polku	Tarkoitus
GET	`/v1/account/monitors`	Kaikki monitorit, uusin ensin, ilman arkistoituja.
POST	`/v1/account/monitors`	Luo monitori.
GET	`/v1/account/monitors/{id}`	Yksi monitori jaksoineen ja viimeisimpine tarkistuksineen.
PATCH	`/v1/account/monitors/{id}`	Muuta tarkistusväliä.
POST	`/v1/account/monitors/{id}/pause`	Keskeytä.
POST	`/v1/account/monitors/{id}/resume`	Jatka.
DELETE	`/v1/account/monitors/{id}`	Arkistoi.
GET	`/v1/account/monitoring/pricing`	Välin hinta.

Idempotency-Key

Jokainen kirjoituspyyntö tarvitsee headerin Idempotency-Key, yksilöllisen arvon toimintoa kohden, mieluiten UUID:n. Ilman sitä API vastaa 428.

Jos toistat pyynnön samalla avaimella ja samalla datalla 24 tunnin sisällä, saat tallennetun vastauksen takaisin. Siinä on header Idempotency-Status: replayed. Näin verkkovirhe ei luo toista monitoria.

Tämä koskee myös virhevastauksia. Uuteen yritykseen korjauksen jälkeen käytä siis uutta avainta. Sama avain eri datalla palauttaa 409.

Sallittu on enintään 128 merkkiä: kirjaimia, numeroita ja . _ : -. Ensimmäinen merkki on kirjain tai numero. Muun muotoinen avain palauttaa 400.

Luo monitori

Tarvitset yrityksen entity_id:n ja vähintään yhden vahvistetun webhook-päätepisteen, katso account/webhook-endpoints.

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

Parametrit
Nimi	Tyyppi	Kuvaus	Esimerkki
Idempotency-KeyHeader	merkkijonopakollinen	Yksilöllinen arvo toimintoa kohden, mieluiten UUID. Katso Idempotency-Key.Rajat: 1–128 merkkiä	`req-20260802-01`
entity_idBody	merkkijonopakollinen	Yrityksen `entity_id` päätepisteestä fetch-organization tai search-organizations.Rajat: 1–128 merkkiä	`94eb910fef13f94585c48c263fa446d4`
labelBody	merkkijonovalinnainen	Monitorin nimi.Rajat: enintään 200 merkkiä	`Hetzner Online GmbH`
poll_interval_daysBody	kokonaislukupakollinen	Tarkistusväli päivinä.Rajat: 1–30	`7`
endpoint_idsBody	lista: stringpakollinen	Webhook-päätepisteidesi tunnisteet (`wep_…`). Jokaisen on oltava aktiivinen ja vahvistettu.Rajat: 1–10 kohdetta	`["wep_01m6b3j1g0cdz98hw8zdefbf52"]`

API vastaa 202: monitori on luotu, ja lähtötilanne ja aktivointi suoritetaan taustalla. meta.billing.charged_credits näyttää, ettei tästä veloitettu mitään.

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 · Esimerkkivastaus: uusi monitori, esimerkissämme yritykselle Hetzner Online GmbH, Ansbach HRB 6089

API:n kautta määrität webhook-päätepisteet monitoria luodessasi. Toisen webhook-päätepisteen yhdistät kohdassa Tili › Monitorointi toiminnolla ”Yhdistä kohde” ilman lisämaksua.

Listaa ja päivitä monitoreja

GET /v1/account/monitors palauttaa enintään 100 monitoria kentässä monitors sekä kentän total. Arkistoidut eivät ole listassa.

GET /v1/account/monitors/{id} näyttää lisäksi nykyisen jakson kentässä billing_cycle ja viimeisimmät tarkistukset kentässä recent_runs.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec",
    headers={"x-api-key": "SINUN_API_AVAIMESI"},
)
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": "SINUN_API_AVAIMESI" },
});
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 · Esimerkkivastaus: aktiivinen monitori päivittäisellä tarkistuksella, jälleen yritykselle Hetzner Online GmbH

Monitorin kentät
Kenttä	Merkitys
id	Monitorin tunniste, alkaa `mon_`.
entity_id	Seurattu yritys.
poll_interval_days	Tarkistusväli päivinä.
status, status_reason	Tila, katso yllä. `status_reason` kertoo syyn.
baseline_completed_at, activated_at, last_succeeded_at	Lähtötilanteen, aktivoinnin ja viimeisen onnistuneen tarkistuksen ajankohdat.
next_poll_at	Seuraava ajoitettu tarkistus, vain aktiivisilla monitoreilla.
billing_cycle	Nykyinen jakso: alku, loppu, hinta, sisältyvät tarkistukset ja tähän mennessä tehdyt tarkistukset.
recent_runs	Viimeisimmät tarkistukset tuloksineen, veloituksineen ja uusien signaalien määrineen kentässä `events_new`.

PATCH /v1/account/monitors/{id} muuttaa tarkistusväliä. Seuraava tarkistus tulee silloin uudella välillä muutoksesta laskien.

Nykyinen jakso säilyttää hintansa ja sisältyvät tarkistuksensa. Uusi hinta pätee seuraavasta jaksosta alkaen. Lyhyempi väli voi laukaista lisätarkistuksia nykyisessä jaksossa.

curl -X PATCH "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz" \
  -H "x-api-key: SINUN_API_AVAIMESI" \
  -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": "SINUN_API_AVAIMESI",
        "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": "SINUN_API_AVAIMESI",
    "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 · Esimerkkivastaus: väli muutettu 30 päivään

Keskeytä, jatka, arkistoi

POST …/{id}/pause pysäyttää aktiivisen monitorin. Maksettu jakso kuluu loppuun, eikä mitään hyvitetä.

POST …/{id}/resume jatkaa keskeytettyä monitoria tai virhetilassa olevaa monitoria. Tarkistamme webhook-päätepisteet, saldon ja hinnan uudelleen.

Nykyisen maksetun jakson aikana jatkaminen ei maksa mitään. Jos jakso on kulunut loppuun, uusi jakso alkaa nyt nykyiseen hintaan. meta.request_credit_cost näyttää summan.

Jos esimerkiksi vahvistettu webhook-päätepiste puuttuu, API vastaa silti 200, mutta arvolla meta.activated: false. Monitorin tila ja status_reason kertovat syyn.

Jos hinta on muuttunut, aktiivinen monitori pysähtyy jakson lopussa tilalla pricing_consent_required. Toiminnolla resume hyväksyt uuden hinnan.

DELETE …/{id} arkistoi monitorin lopullisesti. Tämä on pysyvää eikä hyvitä mitään.

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

Jos poistat webhook-päätepisteen käytöstä tai arkistoit sen, kaikki monitorit ilman muuta webhook-päätepistettä keskeytyvät tilalla paused_configuration. Kun otat webhook-päätepisteen taas käyttöön, jatka monitoria toiminnolla resume.

Virheet

Virheillä on rakenne {"error": "…", "meta": {"message": "…"}}. Tarkista ohjelmassasi kentän error arvo. Kentän meta.message teksti on englanniksi ja voi muuttua. Virheet eivät maksa mitään.

Virheet
Tila	Syy	Mitä voit tehdä
400	`api_key` on URL-osoitteessa.	Lähetä avain headerissa `x-api-key`.
400	`Idempotency-Key`:n muoto on virheellinen.	Korjaa muoto, esimerkiksi käytä UUID:tä.
401	API-avain tai token puuttuu tai on virheellinen.	Lähetä avain headerissa `x-api-key`.
403	Bearer-tokenilta puuttuu oikeus `account:read`.	Käytä API-avainta tai tokenia, jolla on `account:read`.
403	Tilisi sähköpostiosoitetta ei ole vielä vahvistettu, tai tili on lukittu.	Avaa vahvistussähköpostin linkki. Jos tili on lukittu, tuki voi auttaa.
403	Bearer-tokenilta puuttuu oikeus `monitoring:manage`.	Käytä API-avainta tai admin-tokenia.
404	Tililläsi ei ole monitoria tällä tunnisteella.	Tarkista tunniste.
409	Tälle yritykselle on jo monitori (`duplicate_monitor`).	Käytä olemassa olevaa monitoria tai arkistoi se ensin.
409	`Idempotency-Key` on jo käytetty eri datalla, on yli 24 tuntia vanha tai on yhä käsittelyssä.	Käytä uutta avainta tai odota hetki.
422	Arvo on virheellinen: `invalid_subject`, `invalid_interval`, `endpoint_required`, `monitor_limit` tai `not_resumable`.	Korjaa arvo.
428	Header `Idempotency-Key` puuttuu.	Lähetä header.
429	Liian monta pyyntöä.	Yritä uudelleen ajan `Retry-After` jälkeen.
429	`creation_rate_limited`: liian monta uutta monitoria 24 tunnin sisällä.	Yritä uudelleen ajan `Retry-After` jälkeen.
503	Monitoring ei ole tilapäisesti käytettävissä.	Yritä hieman myöhemmin uudelleen.

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 · Toinen monitori samalle yritykselle