Skip to main content

​
Session History

Retrieve paginated session history for any identifier. Returns raw snapshot data with full pagination support.

​
Endpoint

GET /pub/{public_key}/{secret_key}/history/{search_type}/{value}
No JWT required — authenticates via public_key and secret_key in the URL.

​
Parameters

ParameterInTypeRequiredDescription
public_keypathstring✅Domain public key
secret_keypathstring✅Domain secret key
search_typepathstring✅user_hid, visitor_id, device_id, webrtc_ip, ip, request_id
valuepathstring✅The identifier to search for
limitqueryintegerNumber of results (1–100, default 20)
offsetqueryintegerPagination offset (default 0)

​
Response

{
  "total": 142,
  "items": [
    {
      "request_id":    "550e8400-e29b-41d4-a716-446655440000",
      "device_id":     "a1b2c3d4...",
      "visitor_id":    "7f3e9a12-...",
      "user_hid":      "e3b0c442...",
      "ip":            "93.184.216.34",
      "os":            "Windows",
      "country":       "US",
      "score":         42,
      "details":       [{"Value": 20, "Description": "Is datacenter"}],
      "created_at":    "2026-04-14T10:00:00Z"
    }
  ]
}

​
Examples

​
Get all sessions for a user (paginated)

# Page 1
curl "https://api.shieldlabs.ai/pub/YOUR_PUBLIC_KEY/YOUR_SECRET/history/user_hid/e3b0c44298fc...?limit=20&offset=0"

# Page 2
curl "https://api.shieldlabs.ai/pub/YOUR_PUBLIC_KEY/YOUR_SECRET/history/user_hid/e3b0c44298fc...?limit=20&offset=20"

​
Check if a device has a history of high-risk sessions

async function getDeviceHistory(deviceId) {
  const url = `https://api.shieldlabs.ai/pub/${PUBLIC_KEY}/${SECRET_KEY}/history/device_id/${deviceId}?limit=50`;
  const res = await fetch(url);
  const { items } = await res.json();

  const highRiskCount = items.filter(s => s.score >= 70).length;
  const avgScore = items.reduce((sum, s) => sum + s.score, 0) / items.length;

  return { highRiskCount, avgScore, total: items.length };
}

​
All sessions for an IP in the last 24 hours

curl "https://api.shieldlabs.ai/pub/YOUR_KEY/YOUR_SECRET/history/ip/93.184.216.34?limit=100"

​
Error responses

StatusBodyMeaning
401{"error": "unauthorized"}Invalid public_key or secret_key
404{"error": "not found"}No sessions found