Skip to main content
History reads the domain that owns your Private API Key. Call Domain first and use the returned id as {domain_id}. That value is a UUID, not the hostname. The literal all returns 403. Search lists identifications or users. Card reads one record.

Methods

A list of visitor, device, or ip returns 403. Read those one record at a time.

Authentication

string
required
Bearer PRIVATE_API_KEY. Use the domain’s Private API Key, not its browser Public Key or Management Secret Key.
A missing identification returns 404. 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

string
required
Public domain id from GET /api/v1/domains.
string
required
identifications or user for a list. identifications, user, visitor, device, or ip for one record.
string
required
The record id. Required on the one-record path. URL-encode it once. An IP is IPv4.
A hostname, all, an empty id, . or .., a slash, a backslash, or a control character is rejected.

Query parameters

string
Window start, RFC 3339. Send from and to together, or omit both. A list defaults to the last 24 hours.
string
Window end, RFC 3339.
string
Value of the History-Snapshot response header. Sending it continues the same read.
integer
default:"20"
List page size, from 1 to 100.
string
Continuation from next_page_token.
string
Repeat for trusted, suspicious, or dangerous.
string
One user id. Only on the user list. A second value is rejected.
boolean
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.
string
Repeat a public signal code, such as vpn. Several codes combine with OR.
string
Traffic source. Repeat with campaign. At most 8 values together, matched if any value matches. _empty means no referrer.
string
Campaign name. No campaign matches visits with no campaign.
integer
default:"3"
Minimum linked accounts for a high-risk event, from 3 to 99.
integer
default:"4"
Minimum linked devices for a high-risk event, from 4 to 99.
string
Only on a device record: legacy or fp21_record.
A nested filter, chips, or offset returns 400.

Response

A list returns { "data": [ ... ], "next_page_token": null }. One record returns { "data": { ... } }. Successful responses also send History-Snapshot, History-Snapshot-Expires-At, History-Window-From, and History-Window-To.
object | object[]
required
One card, or the cards for this page. See History card.
string
Present on a list. null means there is no next page.
History and webhooks have different field names:

Pagination

List one user’s identifications and follow next_page_token:
History reads do not consume identification quota. The History endpoint allows 15 requests per second per domain; back off on 429.

Errors