/v1/account/monitors
account/monitors
モニタリング：企業を監視させる。作成、一時停止、削除。
モニターは、あなたの代わりに企業を監視します。固定の間隔で新しいシグナルをチェックし、新しいシグナルをそれぞれWebhookであなたのWebhookエンドポイントに送ります。
コストと制限
| 内容 | クレジット |
|---|---|
| 毎日 チェックするモニター、30 日間 | 50 |
| 3 日ごとに チェックするモニター、30 日間 | 40 |
| 7 日ごとに チェックするモニター、30 日間 | 20 |
| 30 日ごとに チェックするモニター、30 日間 | 10 |
| 期間内の追加の成功チェック1回ごと | +2 |
制限：1分あたり 30 リクエスト。 作成、更新、削除：1分あたり 10 回。
モニターの作成と最初のベースラインは無料です。30 日間のサイクルは、モニターが有効になった時点で課金されます。料金はチェック間隔によって決まり、1サイクル内でその間隔が予定するすべてのチェックを含みます。
2つの段階の間の間隔は、次に頻度の高い段階と同じ料金です。4日ごとは3日ごとと同じ料金です。
追加のチェックは、主にサイクルの途中で間隔を短くした場合に発生します。成功した追加チェックは1回ごとに表の額がかかります。
30 日後、サイクルはその時点の料金で自動的に更新されます。失敗したチェックに料金はかかりません。一時停止、アーカイブ、間隔の変更をしても、返金はありません。
各アカウントは同時に最大 50 個のモニターを持て、企業1社につき1つです。24時間以内に作成できるモニターは最大 50 個で、アーカイブ済みのものもカウントされます。
間隔の料金はGET /v1/account/monitoring/pricingで無料で得られます。ここでは7日ごとのチェックの例です：
curl -G "https://handelsregister.ai/api/v1/account/monitoring/pricing" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'poll_interval_days=7'
import requests response = requests.get( "https://handelsregister.ai/api/v1/account/monitoring/pricing", headers={"x-api-key": "YOUR_API_KEY"}, 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": "YOUR_API_KEY" }, }); 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}
モニターのしくみ
- 作成。企業、チェック間隔、少なくとも1つの検証済みWebhookエンドポイントを指定します。モニターはステータス
initializingで始まります。 - ベースライン。直近数日のシグナルを既知として記録します。これらは配信されないため、その後の新しいものだけを受け取ります。
- 有効化。サイクルを課金し、モニターは
activeになり、すぐに最初のチェックを行います。 - チェック。その後は選んだ間隔でチェックします。新しいシグナルごとに、モニター1つにつき1件のメッセージがWebhookエンドポイントに送られます。
- 更新。各サイクルの後、残高が足りている限り、次のサイクルが自動的に課金されます。
チェック間隔は 1～30 日です。チェックの正確な時刻は1時間以内で前後することがあります。各チェックは数日さかのぼって確認するため、遅れて公開された登記も届きます。
モニターはプランのSignalsトピックを配信します：すべてのアカウントで5つ、倒産はPro、組織再編とM&AはMaxで。Webhookは、signalsと同じシグナルをフィールドdata.signalで運びます。
| ステータス | 意味 |
|---|---|
| initializing | 作成済み。ベースラインと有効化が実行中。 |
| active | 選んだ間隔でチェック中。 |
| paused_user | あなたが一時停止した。 |
| paused_configuration | 有効で検証済みのWebhookエンドポイントが接続されていない。 |
| paused_billing | 残高がサイクルまたは追加チェックに足りない。または料金が変わり、あなたの同意を待っている。 |
| error | 複数のチェックが連続して失敗した。 |
| archived | 完全に終了。IDでモニターを読み取ることはできますが、リストには表示されません。 |
一時停止中のモニターやエラーでは、status_reasonが理由を説明します。例えばno_verified_endpointやinsufficient_cycle_floorです。
エンドポイント
すべてのパスは/v1/account以下にあります。読み書きには、ヘッダーx-api-keyのAPIキーを使います。
| メソッド | パス | 用途 |
|---|---|---|
| GET |
/v1/account/monitors |
すべてのモニター（新しい順、アーカイブ済みを除く）。 |
| POST |
/v1/account/monitors |
モニターを作成。 |
| GET |
/v1/account/monitors/{id} |
サイクルと最新のチェック付きのモニター1つ。 |
| PATCH |
/v1/account/monitors/{id} |
チェック間隔を変更。 |
| POST |
/v1/account/monitors/{id}/pause |
一時停止。 |
| POST |
/v1/account/monitors/{id}/resume |
再開。 |
| DELETE |
/v1/account/monitors/{id} |
アーカイブ。 |
| GET |
/v1/account/monitoring/pricing |
間隔の料金。 |
Idempotency-Key
すべての書き込みリクエストには、操作ごとに一意の値（できればUUID）を入れたヘッダーIdempotency-Keyが必要です。ない場合、APIは428を返します。
24時間以内に同じキーと同じデータでリクエストを繰り返すと、保存されたレスポンスが返ります。そこにはヘッダーIdempotency-Status: replayedが付きます。そのため、ネットワークエラーで2つ目のモニターが作成されることはありません。
これはエラーレスポンスにも当てはまります。修正後の新しい試行には、新しいキーを使ってください。同じキーで異なるデータを指定すると409が返ります。
最大128文字が使えます：英字、数字、. _ : -。最初の文字は英字か数字です。それ以外の形式のキーでは400が返ります。
モニターを作成する
企業のentity_idと、少なくとも1つの検証済みWebhookエンドポイントが必要です。account/webhook-endpointsを参照。
curl -X POST "https://handelsregister.ai/api/v1/account/monitors" \ -H "x-api-key: YOUR_API_KEY" \ -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": "YOUR_API_KEY", "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": "YOUR_API_KEY", "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();
| 名前 | 型 | 説明 | 例 |
|---|---|---|---|
| Idempotency-Keyヘッダー | 文字列必須 | 操作ごとに一意の値。できればUUID。Idempotency-Keyを参照。制限: 1～128 文字 |
req-20260802-01 |
| entity_idボディ | 文字列必須 |
fetch-organizationまたはsearch-organizationsで得られる企業のentity_id。制限: 1～128 文字 |
94eb910fef13f94585c48c263fa446d4 |
| labelボディ | 文字列任意 | モニターの名前。制限: 200 文字以下 |
Hetzner Online GmbH |
| poll_interval_daysボディ | 整数必須 | チェック間隔（日数）。制限: 1～30 |
7 |
| endpoint_idsボディ | string のリスト必須 |
WebhookエンドポイントのID（wep_…）。それぞれ有効で検証済みである必要があります。制限: 1～10 件 |
["wep_01m6b3j1g0cdz98hw8zdefbf52"] |
APIは202を返します：モニターは作成され、ベースラインと有効化はバックグラウンドで実行されます。meta.billing.charged_creditsで、この時点では何も課金されていないことがわかります。
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}
APIでは、Webhookエンドポイントはモニターの作成時に設定します。別のWebhookエンドポイントは、アカウント › モニタリングの「送信先を接続」で、追加料金なしで接続できます。
モニターの一覧と更新
GET /v1/account/monitorsは、最大 100 個のモニターをmonitorsに入れ、totalとともに返します。アーカイブ済みのものはリストにありません。
GET /v1/account/monitors/{id}では、現在のサイクルがbilling_cycleに、最新のチェックがrecent_runsに表示されます。
curl -G "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec" \ -H "x-api-key: YOUR_API_KEY"
import requests response = requests.get( "https://handelsregister.ai/api/v1/account/monitors/mon_01m65pn3vm11sjjp1j076cbvec", headers={"x-api-key": "YOUR_API_KEY"}, ) 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": "YOUR_API_KEY" }, }); 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}
| フィールド | 意味 |
|---|---|
| id |
モニターのID。mon_で始まります。
|
| entity_id | 監視対象の企業。 |
| poll_interval_days | チェック間隔（日数）。 |
| status, status_reason |
ステータス（上記参照）。status_reasonが理由を示します。
|
| baseline_completed_at, activated_at, last_succeeded_at | ベースライン、有効化、最後に成功したチェックの時刻。 |
| next_poll_at | 次に予定されているチェック。有効なモニターのみ。 |
| billing_cycle | 現在のサイクル：開始、終了、料金、含まれるチェック、これまでに実行したチェック。 |
| recent_runs |
最新のチェック。結果、課金、events_newに新しいシグナルの数付き。
|
PATCH /v1/account/monitors/{id}はチェック間隔を変更します。次のチェックは、変更時点から数えて新しい間隔で行われます。
現在のサイクルは料金と含まれるチェックを維持します。新しい料金は次のサイクルから適用されます。間隔を短くすると、現在のサイクルで追加チェックが発生することがあります。
curl -X PATCH "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz" \ -H "x-api-key: YOUR_API_KEY" \ -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": "YOUR_API_KEY", "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": "YOUR_API_KEY", "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}
一時停止、再開、アーカイブ
POST …/{id}/pauseは有効なモニターを停止します。支払い済みのサイクルはそのまま満了まで進み、返金はありません。
POST …/{id}/resumeは、一時停止中のモニターやエラーのあるモニターを再開します。Webhookエンドポイント、残高、料金を再確認します。
支払い済みの現在のサイクル内なら、再開に料金はかかりません。サイクルが満了していれば、その時点の料金で新しいサイクルが始まります。meta.request_credit_costに額が表示されます。
例えば検証済みWebhookエンドポイントがない場合でも、APIは200を返しますが、meta.activated: falseが付きます。モニターのステータスとstatus_reasonが理由を示します。
料金が変わった場合、有効なモニターはサイクルの終わりにpricing_consent_requiredで停止します。resumeで新しい料金に同意します。
DELETE …/{id}はモニターを完全にアーカイブします。これは取り消せず、返金もありません。
curl -X POST "https://handelsregister.ai/api/v1/account/monitors/mon_01m6b3m7945dn7cyvexzv41kjz/resume" \ -H "x-api-key: YOUR_API_KEY" \ -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": "YOUR_API_KEY", "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": "YOUR_API_KEY", "Idempotency-Key": crypto.randomUUID(), }, }); const data = await response.json();
Webhookエンドポイントを無効化またはアーカイブすると、他のWebhookエンドポイントのないモニターはすべて
paused_configurationで一時停止します。Webhookエンドポイントを有効化した後、resumeでモニターを再開してください。
エラー
エラーの構造は{"error": "…", "meta": {"message": "…"}}です。プログラムではerrorの値を確認してください。meta.messageのテキストは英語で、変わることがあります。エラーに料金はかかりません。
| ステータス | 原因 | 対処法 |
|---|---|---|
| 400 |
api_keyがURLにある。 |
キーをヘッダーx-api-keyで送る。 |
| 400 |
Idempotency-Keyの形式が無効。 |
形式を修正する。例えばUUIDを使う。 |
| 401 | APIキーもトークンもないか、無効。 |
キーをヘッダーx-api-keyで送る。 |
| 403 |
Bearerトークンに権限account:readがない。 |
APIキーか、account:read付きのトークンを使う。 |
| 403 | アカウントのメールアドレスがまだ確認されていないか、アカウントがロックされている。 | 確認メールのリンクを開く。アカウントがロックされている場合はサポートが対応できる。 |
| 403 |
Bearerトークンに権限monitoring:manageがない。 |
APIキーか管理者トークンを使う。 |
| 404 | アカウントにこのIDのモニターがない。 | IDを確認する。 |
| 409 |
この企業のモニターがすでにある（duplicate_monitor）。 |
既存のモニターを使うか、先にアーカイブする。 |
| 409 |
Idempotency-Keyがすでに別のデータで使われている、24時間より古い、またはまだ処理中。 |
新しいキーを使うか、少し待つ。 |
| 422 |
値が無効：invalid_subject、invalid_interval、endpoint_required、monitor_limit、not_resumable。 |
値を修正する。 |
| 428 |
ヘッダーIdempotency-Keyがない。 |
ヘッダーを送る。 |
| 429 | リクエストが多すぎる。 |
Retry-Afterの後に再試行する。 |
| 429 |
creation_rate_limited：24時間以内の新しいモニターが多すぎる。 |
Retry-Afterの後に再試行する。 |
| 503 | モニタリングが一時的に利用できない。 | 少し後に再試行する。 |
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}