/v1/account/monitors
account/monitors
监控：让我们监控公司；创建、暂停、删除。
监控替你关注一家公司。我们按固定间隔检查是否有新信号，并将每条新信号通过 Webhook 发送到你的 Webhook 端点。
费用和限制
| 项目 | 积分 |
|---|---|
| 监控 每天 检查一次，为期 30 天 | 50 |
| 监控 每 3 天 检查一次，为期 30 天 | 40 |
| 监控 每 7 天 检查一次，为期 30 天 | 20 |
| 监控 每 30 天 检查一次，为期 30 天 | 10 |
| 周期内每次额外的成功检查 | +2 |
限制：每分钟 30 次请求。 创建、更新和删除：每分钟 10 次。
创建监控和首次基线免费。一旦监控激活，就按 30 天的周期计费。价格取决于检查间隔，涵盖该间隔在一个周期内安排的所有检查。
介于两个档位之间的间隔，按下一个更频繁的档位收费：每四天一次与每三天一次价格相同。
额外检查主要发生在你于周期中途缩短间隔时。每次成功的额外检查按表中金额收费。
30 天后，周期会按届时有效的价格自动续期。失败的检查不收费。暂停、归档或更改间隔时，我们不退款。
每个账户最多可同时拥有 50 个监控，每家公司一个。24 小时内最多可创建 50 个监控；已归档的也计算在内。
你可以通过 GET /v1/account/monitoring/pricing 免费查询某个间隔的价格，此处为每七天检查一次：
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}
监控如何运作
- 创建。你指定公司、检查间隔以及至少一个已验证的 Webhook 端点。监控以状态
initializing开始。 - 基线。我们将最近几天的信号记录为已知。它们不会被投递，因此你只会收到此后的新信号。
- 激活。我们收取周期费用，监控变为
active，并立即进行第一次检查。 - 检查。此后按所选间隔检查。每条新信号都会为每个监控向你的 Webhook 端点触发一条消息。
- 续期。每个周期结束后，只要你的余额足够，就会自动收取下一个周期的费用。
检查间隔为 1 至 30 天。检查的确切时间可能在一小时内浮动。每次检查都会回溯几天，因此延迟公布的条目也会到达。
监控投递你套餐中的 Signals 主题：每个账户五个，Pro 增加破产，Max 增加改制与并购。Webhook 在字段 data.signal 中携带的信号与 signals 相同。
| 状态 | 含义 |
|---|---|
| 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} |
一个监控，含其周期和最近的检查。 |
| 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
每个写请求都需要请求头 Idempotency-Key，即每个操作一个唯一值，最好是 UUID。没有时，API 返回 428。
如果你在 24 小时内用相同的键和相同的数据重复请求，你会得到已存储的响应。它带有请求头 Idempotency-Status: replayed。这样网络错误就不会创建第二个监控。
这也适用于错误响应。因此修正后再次尝试时，请使用新键。相同的键配不同的数据会返回 409。
允许最多 128 个字符：字母、数字和 . _ : -。第一个字符为字母或数字。其他格式的键返回 400。
创建监控
你需要公司的 entity_id 以及至少一个已验证的 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-KeyHeader | 字符串必填 | 每个操作一个唯一值，最好是 UUID。见 Idempotency-Key。限制: 1 至 128 个字符 |
req-20260802-01 |
| entity_idBody | 字符串必填 |
公司的 entity_id，来自 fetch-organization 或 search-organizations。限制: 1 至 128 个字符 |
94eb910fef13f94585c48c263fa446d4 |
| labelBody | 字符串可选 | 监控的名称。限制: 最多 200 个字符 |
Hetzner Online GmbH |
| poll_interval_daysBody | 整数必填 | 检查间隔，以天计。限制: 1 至 30 |
7 |
| endpoint_idsBody | 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 在 monitors 下返回最多 100 个监控，并附 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}