Summarize user, device, visitor or IP
shieldlabs_summarize_entityAggregate recent History API identifications for an account, device, visitor, IP, or cookie to count distinct entities, countries, risk scores, flags, and signals.
Instructions
Aggregate the recent History API identifications of one account (user_hid), device (device_id), browser visitor (visitor_id), IPv4 address (ip) or cookie (cookie_id).
The result is computed by this server from the returned history window (the most recent max_items identifications), and labelled as such: it is not a ShieldLabs verdict. It counts distinct devices, accounts, visitors, countries, IPs and connection types (with the top values), the highest and average Risk Score, band counts, rate-limit markers, detection flags and risk signals seen with counts, and the first and last observed time.
Use it for questions such as: how many accounts used this device, how many devices this account used, which countries an account came from, whether an IP sent automated traffic. Use shieldlabs_search_history to see the individual identifications.
Args:
type ('user_hid' | 'device_id' | 'visitor_id' | 'ip' | 'cookie_id')
value (string): UUID for the ID types, dotted IPv4 for ip, exact User HID for user_hid
max_items (number): 1-500, default 100
response_format ('markdown' | 'json'): default 'markdown'
Returns (json): { "lookup": { type, value }, "computed_from": string, "window": { identifications_analyzed, total_matching, max_items, complete }, "summary": { identifications_analyzed, first_observed_at, last_observed_at, devices: { distinct, top: [{ value, count, truncated? }] }, users, visitors, countries, ips, connection_types, anonymous_identifications, identifications_without_account, identifications_without_device_signals, risk: { max_risk_score, average_risk_score, worst_band, band_counts: { trusted, suspicious, dangerous }, rate_limit_markers }, flags_seen: [{ flag, count }], signals_seen: [{ name, count }], distinct_signals }, "untrusted_data_note": string }
The user count ignores values that do not name an account: null, "anonymous", "fail", "-1" and "unknown". The device count ignores the all-zero device ID (no usable device signals). Averages ignore the 999 rate-limit marker. The History API limit (about 15 requests per second per domain) is shared with the site's own backend: start with the default max_items and raise it only when the window is incomplete and the question needs older identifications.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | What to summarize: user_hid (one of your accounts), device_id (one device), visitor_id (one browser visitor), ip (one IPv4 address) or cookie_id (one browser profile) | |
| value | Yes | Identifier value: a UUID for device_id, visitor_id and cookie_id; a dotted IPv4 address such as 203.0.113.24 for ip; the exact User HID string for user_hid ("anonymous" summarizes anonymous checks; a User HID that contains "/" cannot be searched) | |
| max_items | No | Most recent identifications to analyze, from 1 to 500 (default 100). Each 100 identifications cost one History API request, from the domain's shared limit. | |
| response_format | No | Output format: 'markdown' (default) for readable text, 'json' for structured data | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lookup | Yes | ||
| window | Yes | ||
| summary | Yes | ||
| computed_from | Yes | ||
| untrusted_data_note | Yes |