curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications?limit=20' \
-H "Authorization: Bearer $SHIELDLABS_API_KEY"
{
"data": [
{
"type": "identification",
"id": "550e8400-e29b-41d4-a716-446655440000",
"risk": {
"state": "ok",
"band": "suspicious",
"score": 30
},
"signals": {
"state": "ok",
"items": ["vpn"]
}
}
],
"next_page_token": null
}
Methods
List history
List identifications or users for one domain.
GET
/
api
/
v1
/
domains
/
{domain_id}
/
history
/
{resource}
curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications?limit=20' \
-H "Authorization: Bearer $SHIELDLABS_API_KEY"
{
"data": [
{
"type": "identification",
"id": "550e8400-e29b-41d4-a716-446655440000",
"risk": {
"state": "ok",
"band": "suspicious",
"score": 30
},
"signals": {
"state": "ok",
"items": ["vpn"]
}
}
],
"next_page_token": null
}
Lists
A hostname,
A nested
The read does not consume identification quota. The History API allows 15 requests per second per domain; back off on
identifications or user for one domain. {domain_id} comes from Domain. A list of visitor, device, or ip returns 403. Read those with Card.
curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications?limit=20' \
-H "Authorization: Bearer $SHIELDLABS_API_KEY"
{
"data": [
{
"type": "identification",
"id": "550e8400-e29b-41d4-a716-446655440000",
"risk": {
"state": "ok",
"band": "suspicious",
"score": 30
},
"signals": {
"state": "ok",
"items": ["vpn"]
}
}
],
"next_page_token": null
}
Authentication
Path parameters
Public domain id from Domain.
all, an empty id, . or .., a slash, a backslash, or a control character is rejected.
Query parameters
Window start, RFC 3339. Send
from and to together, or omit both. A list defaults to the last 24 hours.true or false. The same form applies to the other published is_* flags, network_check_incomplete, check_incomplete, ip_mismatch, latency_test, device_spoofing, banned_ip, ai_bot, and ai_browser. Several flags combine with AND.Traffic source. Repeat with
campaign. At most 8 values together, matched if any value matches. _empty means no referrer.filter, chips, or offset returns 400.
Response
A list returns{ "data": [ ... ], "next_page_token": null }. Successful responses also send History-Snapshot, History-Snapshot-Expires-At, History-Window-From, and History-Window-To.
Cards for this page. See History card.
Pagination
List one user’s identifications and follownext_page_token:
async function readAccountHistory(domainId, userHid, maxRows = 500) {
const rows = [];
let pageToken = '';
while (rows.length < maxRows) {
const url = new URL(
`/api/v1/domains/${domainId}/history/user`,
'https://account.shieldlabs.ai',
);
url.searchParams.append('ids', userHid);
url.searchParams.set('limit', String(Math.min(100, maxRows - rows.length)));
if (pageToken) url.searchParams.set('page_token', pageToken);
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.SHIELDLABS_API_KEY}` },
});
if (!response.ok) throw new Error(`History API ${response.status}`);
const page = await response.json();
rows.push(...page.data);
pageToken = page.next_page_token || '';
if (!pageToken || page.data.length === 0) break;
}
return { rows, truncated: Boolean(pageToken) };
}
429.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | invalid_query / invalid_domain_scope / invalid_id | Bad parameter, hostname, or id |
401 | auth message | Missing or invalid Private API Key |
403 | domain_scope_not_supported / entity_list_disabled | all, or a list of visitor, device, or IP |
404 | unknown_domain | No such domain |
429 | rate limit | Domain request limit reached |