Agentscan
Agentscan API
將請求歸類為真人、已知機械人、AI 代理或惡意自動化。
歸類請求
POST/v1/agentscan/check
API 金鑰
參數
- ipstring必填
在您的邊緣看到的用戶端 IP。
- user_agentstring
請求的 User-Agent 標頭。
- ja4string
用戶端的 JA4 TLS 指紋。
- headersobject
請求標頭，用於一致性檢查。
- headless_flagsobject
在瀏覽器中收集的自動化跡象，例如 webdriver。
- request_idstring
您為請求設定的 id，與判定一併保存。
回應欄位
- classstring
human、known_bot、ai_agent 或 malicious_automation。
- confidencenumber
信心分數，範圍 0 至 1。
- actionstring
建議操作：allow、flag 或 block。
- signalsobject
判定依據，按訊號分組。
curl -X POST https://ipscanner.io/v1/agentscan/check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ip": "203.0.113.7",
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) HeadlessChrome/126.0.0.0",
"ja4": "t13d1516h2_8daaf6152771_02713d6af862",
"headers": {
"accept-language": "en-US"
}
}'回應
{
"class": "malicious_automation",
"confidence": 0.91,
"action": "block",
"signals": {
"network_origin": "datacenter",
"anonymized": false,
"headless": true,
"header_consistency": "mismatch",
"allowlist_verified": false,
"ja4": "t13d1516h2_8daaf6152771_02713d6af862"
}
}歸類日誌行
POST/v1/agentscan/batch
API 金鑰
參數
- linesobject[]必填
最多 25,000 條已解析的日誌行，每條包含行號及 ip。
回應欄位
- submittedinteger
收到的項目數。
- processedinteger
已歸類的行。
- failedinteger
無法歸類的行。
- truncatedboolean
執行在結束前停止時為 true。
- byClassobject
各類別的結果數量。
- resultsarray
每行一個判定或錯誤。
curl -X POST https://ipscanner.io/v1/agentscan/batch \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"lines": [
{
"line": 1,
"ip": "66.249.66.1",
"user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
},
{
"line": 2,
"ip": "203.0.113.7",
"user_agent": "python-requests/2.32.3"
}
]
}'回應
{
"submitted": 2,
"processed": 2,
"failed": 0,
"truncated": false,
"reason": "",
"byClass": {
"known_bot": 1,
"malicious_automation": 1
},
"results": [
{
"line": 1,
"ip": "66.249.66.1",
"class": "known_bot",
"confidence": 0.99,
"action": "allow"
},
{
"line": 2,
"ip": "203.0.113.7",
"class": "malicious_automation",
"confidence": 0.84,
"action": "block"
}
],
"asOf": "2026-10-06T14:05:00Z"
}驗證爬蟲
POST/v1/agentscan/verify
API 金鑰
參數
- ipstring必填
爬蟲請求的來源 IP。
- botstring
要驗證的爬蟲 slug，例如 googlebot。
- user_agentstring
用於驗證的 User-Agent，可代替 bot slug。
回應欄位
- outcomestring
verified、spoofed 或 unverifiable。
- methodstring
爬蟲的驗證方式，例如 ip-list+reverse-dns。
- crawlerstring
爬蟲的顯示名稱。
- summarystring
一句話的偵測結果。
- checksarray
執行的每項檢查及其狀態。
- hostnamestring
該 IP 的反向 DNS 名稱。
- checkedAtstring
偵測的時間。
curl -X POST https://ipscanner.io/v1/agentscan/verify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip":"66.249.66.1","bot":"googlebot"}'回應
{
"ip": "66.249.66.1",
"slug": "googlebot",
"crawler": "Googlebot",
"outcome": "verified",
"method": "ip-list+reverse-dns",
"summary": "Address is in Google's published Googlebot ranges and reverse DNS confirms it.",
"checks": [
{
"name": "published_range",
"status": "pass",
"detail": "66.249.66.0/27"
},
{
"name": "reverse_dns",
"status": "pass",
"detail": "crawl-66-249-66-1.googlebot.com"
}
],
"networkOrigin": "hosting",
"anonymized": false,
"asn": "AS15169",
"asnName": "GOOGLE",
"country": "US",
"hostname": "crawl-66-249-66-1.googlebot.com",
"docs": "https://developers.google.com/search/docs/crawling-indexing/verifying-googlebot",
"checkedAt": "2026-10-06T14:05:00Z"
}列出允許清單
GET/v1/agentscan/allowlist
API 金鑰
回應欄位
- agents[].identstring
爬蟲或代理的識別碼。
- agents[].typestring
search、ai_crawler 或 partner。
- agents[].verificationMethodstring
請求與此項目的比對方式。
- agents[].customerIdinteger | null
您新增的項目為您的帳戶 id；全域項目為 null。
curl https://ipscanner.io/v1/agentscan/allowlist \
-H "Authorization: Bearer YOUR_API_KEY"回應
{
"agents": [
{
"id": 1,
"ident": "googlebot",
"type": "search",
"verificationMethod": "reverse_dns:googlebot.com,google.com",
"customerId": null,
"createdAt": "2026-03-01T00:00:00Z"
},
{
"id": 42,
"ident": "partnerbot",
"type": "partner",
"verificationMethod": "ua_match",
"customerId": 17,
"createdAt": "2026-09-12T08:30:00Z"
}
]
}歸類您自己的連線
POST/v1/agentscan/self
API 金鑰不計入用量
參數
- ipstring
覆寫 IP。預設為呼叫方 IP。
- user_agentstring
請求的 User-Agent 標頭。
- headersobject
請求標頭，用於一致性檢查。
- ja4string
用戶端的 JA4 TLS 指紋。
回應欄位
- ipstring
被偵測的 IP 位址。
- ja4Sourcestring
指紋來源：edge、client 或 unavailable。
- classstring
human、known_bot、ai_agent 或 malicious_automation。
- confidencenumber
信心分數，範圍 0 至 1。
- actionstring
建議操作：allow、flag 或 block。
- signalsobject
判定依據，按訊號分組。
- meteredboolean
固定為 false：自我檢查不消耗額度。
curl -X POST https://ipscanner.io/v1/agentscan/self \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'回應
{
"ip": "203.0.113.42",
"userAgent": "curl/8.7.1",
"ja4": "t13d4907h2_0d8feac7bc37_7395dae3b2f3",
"ja4Source": "edge",
"class": "ai_agent",
"confidence": 0.62,
"action": "flag",
"signals": {
"network_origin": "residential_clean",
"headless": false,
"ai_ident": false
},
"metered": false,
"asOf": "2026-10-06T14:05:00Z"
}