Skip to main content

​
Session History

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

​
Endpoint

GET https://account.shieldlabs.ai/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 (32 hex chars)
secret_keypathstring✅Domain secret key (32 hex chars)
search_typepathstring✅user_hid, visitor_id, device_id, cookie_id, session_id, ip, request_id
valuepathstring✅The identifier to search for
limitqueryintegerNumber of results (1–100, default 20)
offsetqueryintegerPagination offset (default 0)

​
Response

{
  "total": 142,
  "data": [
    {
      "request_id":    "550e8400-e29b-41d4-a716-446655440000",
      "device_id":     "6ba7b810-9dad-11d1-80b4-00c04fd430c9",
      "visitor_id":    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_hid":      "e3b0c442...",
      "ip":            "93.184.216.34",
      "os":            "Windows",
      "country":       "US",
      "score":         42,
      "details":       [{"Value": 10, "Description": "Is datacenter"}],
      "created_at":    "2026-04-14T10:00:00Z"
    }
  ]
}

​
Examples

​
Get all sessions for a user (paginated)

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

# Page 2
curl "https://account.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://account.shieldlabs.ai/pub/${PUBLIC_KEY}/${SECRET_KEY}/history/device_id/${deviceId}?limit=50`;
  const res = await fetch(url);
  const { data, total } = await res.json();

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

  return { highRiskCount, avgScore, total };
}

​
All sessions for an IP

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

​
Error responses

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