curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications/550e8400-e29b-41d4-a716-446655440000' \
-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"]
}
}
}
Methods
Read one history record
Read one identification, user, visitor, device, or IP.
GET
/
api
/
v1
/
domains
/
{domain_id}
/
history
/
{resource}
/
{resource_id}
curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications/550e8400-e29b-41d4-a716-446655440000' \
-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"]
}
}
}
Reads one record.
A hostname,
History and webhooks have different field names:
The read does not consume identification quota. The History API allows 15 requests per second per domain.
{domain_id} comes from Domain. {resource} is identifications, user, visitor, device, or ip.
curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications/550e8400-e29b-41d4-a716-446655440000' \
-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"]
}
}
}
Authentication
A missing identification returns404. For a new Identification ID, use a bounded retry or an SDK retrieval helper. Bind the result to the expected domain, account and protected action before using it.
Path parameters
Public domain id from Domain.
all, an empty id, . or .., a slash, a backslash, or a control character is rejected.
Query parameters
List filters such asfrom, to, risk_bands, and is_vpn also apply. See Search.
Response
One record returns{ "data": { ... } }. Successful responses also send History-Snapshot, History-Snapshot-Expires-At, History-Window-From, and History-Window-To.
The card. See History card.
| History card | Scored webhook data |
|---|---|
id when type is identification | identification_id |
risk.score when risk.state is ok | risk_score |
risk.band | Trusted, Suspicious or Dangerous label for that score |
signals.items | Signal names in signals. The webhook also includes each contribution. |
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 | all is not a domain id |
404 | not_found / unknown_domain | No such record or domain |
429 | rate limit | Domain request limit reached |