Search events

Search

The /v4/events endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include:

• Searching for events associated with a single visitor_id within a time range to get historical behavior of a visitor.
• Searching for events associated with a single linked_id within a time range to get all events associated with your internal account identifier.
• Excluding all bot traffic from the query (good and bad bots)

By default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events.

• Use start and end to specify the time range of the search.
• Use reverse=true to sort the results oldest first.
• Use limit to specify the number of events to return.
• Use pagination_key to get the next page of results if there are more than limit events.

Filtering events with the suspect flag

The /v4/events endpoint unlocks a powerful method for fraud protection analytics. The suspect flag is exposed in all events where it was previously set by the update API.

You can also apply the suspect query parameter as a filter to find all potentially fraudulent activity that you previously marked as suspect. This helps identify patterns of fraudulent behavior.

Environment scoping

If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments.

Smart Signals not activated for your workspace or are not included in the response.

GET /events

Search events

cURL

curl --request GET \
  --url https://api.fpjs.io/v4/events \
  --header 'Authorization: Bearer <token>'

200

200-ok

{ "events": [ { "linked_id": "somelinkedId", "tags": {}, "timestamp": 1708102555327, "event_id": "1708102555327.NLOjmg", "incremental_identification_status": "completed", "url": "https://www.example.com/login?hope{this{works[!", "ip_address": "61.127.217.15", "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ....", "client_referrer": "https://example.com/blog/my-article", "browser_details": { "browser_name": "Chrome", "browser_major_version": "74", "browser_full_version": "74.0.3729", "os": "Windows", "os_version": "7", "device": "Other" }, "identification": { "visitor_id": "Ibk1527CUFmcnjLwIs4A9", "confidence": { "score": 0.97, "version": "1.1" }, "visitor_found": false, "first_seen_at": 1708102555327, "last_seen_at": 1708102555327 }, "supplementary_id_high_recall": { "visitor_id": "0jnGMkPYXX37DqVa4ZIO3f_hr", "visitor_found": true, "confidence": { "score": 0, "version": "Not Supported" }, "first_seen_at": 1778086556130, "last_seen_at": 1778604975494 }, "proximity": { "id": "w1aTfd4MCvl", "precision_radius": 10, "confidence": 0.95 }, "bot": "not_detected", "root_apps": false, "emulator": false, "ip_info": { "v4": { "address": "94.142.239.124", "geolocation": { "accuracy_radius": 20, "latitude": 50.05, "longitude": 14.4, "postal_code": "150 00", "timezone": "Europe/Prague", "city_name": "Prague", "country_code": "CZ", "country_name": "Czechia", "continent_code": "EU", "continent_name": "Europe", "subdivisions": [ { "iso_code": "10", "name": "Hlavni mesto Praha" } ] }, "asn": "7922", "asn_name": "COMCAST-7922", "asn_network": "73.136.0.0/13", "asn_type": "isp", "datacenter_result": true, "datacenter_name": "DediPath" }, "v6": { "address": "2001:db8:3333:4444:5555:6666:7777:8888", "geolocation": { "accuracy_radius": 5, "latitude": 49.982, "longitude": 36.2566, "postal_code": "10112", "timezone": "Europe/Berlin", "city_name": "Berlin", "country_code": "DE", "country_name": "Germany", "continent_code": "EU", "continent_name": "Europe", "subdivisions": [ { "iso_code": "BE", "name": "Land Berlin" } ] }, "asn": "6805", "asn_name": "Telefonica Germany", "asn_network": "2a02:3100::/24", "asn_type": "isp", "datacenter_result": false, "datacenter_name": "" } }, "ip_blocklist": { "email_spam": false, "attack_source": false, "tor_node": false }, "proxy": true, "proxy_confidence": "low", "proxy_details": { "proxy_type": "residential", "last_seen_at": 1708102555327, "provider": "Massive" }, "proxy_ml_score": 0.2, "vpn": false, "vpn_confidence": "high", "vpn_origin_timezone": "Europe/Berlin", "vpn_origin_country": "unknown", "vpn_methods": { "timezone_mismatch": false, "public_vpn": false, "auxiliary_mobile": false, "os_mismatch": false, "relay": false }, "incognito": false, "tampering": false, "tampering_confidence": "high", "tampering_ml_score": 0.3231, "tampering_details": { "anomaly_score": 0.1955, "anti_detect_browser": false }, "cloned_app": false, "factory_reset_timestamp": 0, "jailbroken": false, "simulator": false, "frida": false, "privacy_settings": false, "virtual_machine": false, "virtual_machine_ml_score": 0.2, "location_spoofing": false, "velocity": { "distinct_ip": { "5_minutes": 1, "1_hour": 1, "24_hours": 1 }, "distinct_country": { "5_minutes": 1, "1_hour": 2, "24_hours": 2 }, "events": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 }, "ip_events": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 }, "distinct_ip_by_linked_id": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 }, "distinct_visitor_id_by_linked_id": { "5_minutes": 1, "1_hour": 5, "24_hours": 5 } }, "developer_tools": false, "mitm_attack": false, "sdk": { "platform": "js", "version": "3.11.10", "integrations": [ { "name": "fingerprint-pro-react", "version": "3.11.10", "subintegration": { "name": "preact", "version": "10.21.0" } } ] }, "replayed": false, "high_activity_device": false, "raw_device_attributes": { "math": "5f030fa7d2e5f9f757bfaf81642eb1a6", "vendor": "Google Inc.", "plugins": [ { "description": "Portable Document Format", "mimeTypes": [ { "suffixes": "pdf", "type": "application/pdf" }, { "suffixes": "pdf", "type": "text/pdf" } ], "name": "PDF Viewer" } ], "webgl_extensions": { "context_attributes": "6b1ed336830d2bc96442a9d76373252a", "extension_parameters": "86a8abb36f0cb30b5946dec0c761d042", "extensions": "57233d7b10f89fcd1ff95e3837ccd72d", "parameters": "ea118c48e308bc4b0677118bbb3019ec", "shader_precisions": "f223dfbcd580cf142da156d93790eb83", "unsupported_extensions": [] }, "cookies_enabled": true, "webgl_basics": { "renderer": "WebKit WebGL", "renderer_unmasked": "ANGLE (Apple, ANGLE Metal Renderer: Apple M4, Unspecified Version)", "shading_language_version": "WebGL GLSL ES 1.0 (OpenGL ES GLSL ES 1.0 Chromium)", "vendor": "WebKit", "vendor_unmasked": "Google Inc. (Apple)", "version": "WebGL 1.0 (OpenGL ES 2.0 Chromium)" }, "canvas": { "geometry": "db3c1462576a399a03ae93d0ab9eb5c4", "text": "70c3d3f7eb4408dc37a6bf8af1c51029", "winding": true }, "hardware_concurrency": 10, "languages": [ [ "en-US" ] ], "color_depth": 24, "fonts": [ "Arial Unicode MS", "Gill Sans", "Helvetica Neue", "Menlo" ], "indexed_db": true, "touch_support": { "max_touch_points": 0, "touch_event": false, "touch_start": false }, "device_memory": 8, "oscpu": "Windows NT 6.1; Win64; x64", "architecture": 127, "screen_resolution": [ 1920, 1080 ], "timezone": "America/Sao_Paulo", "emoji": { "bottom": 32, "font": "Times", "height": 18, "left": 8, "right": 1608, "top": 14, "width": 1600, "x": 8, "y": 14 }, "font_preferences": { "apple": 147.5625, "default": 147.5625, "min": 9.234375, "mono": 133.0625, "sans": 144.015625, "serif": 147.5625, "system": 146.09375 }, "platform": "MacIntel", "local_storage": true, "session_storage": true, "date_time_locale": "en-US", "audio": 124.04347745512496 }, "rare_device": false, "rare_device_percentile_bucket": "<p95", "labels": [ { "label": "fraud", "prediction": false, "ml_score": 0.01 } ] } ], "pagination_key": "1708102555327" }

Authorizations

Authorization · string · header · required

Add your Secret API Key to the Authorization header using the standard Bearer format: Authorization: Bearer <secret_api_key>

Query Parameters

limit · integer<int32> · default: 10

Maximum number of events to return. Results are selected from the time range (start, end), ordered by reverse, then truncated to provided limit size. So reverse=true returns the oldest N=limit events, otherwise the newest N=limit events.

Required range: 1 <= x <= 100

Example:

10

pagination_key · string

Use pagination_key to get the next page of results.

When more results are available (e.g., you requested up to 100 results for your query using limit, but there are more than 100 events total matching your request), the pagination_key field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. In the following request, use that value in the pagination_key parameter to get the next page of results:

1. First request, returning most recent 100 events: GET api-base-url/events?limit=100
2. Use response.pagination_key to get the next page of results: GET api-base-url/events?limit=100&pagination_key=1740815825085

visitor_id · string

Unique visitor identifier issued by Fingerprint Identification and all active Smart Signals.

Filter events by matching Visitor ID (identification.visitor_id property).

high_recall_id · string

The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental.

Filter events by matching High Recall ID (supplementary_id_high_recall.visitor_id property).

bot · enum<string>

Filter events by the Bot Detection result, specifically: all - events where any kind of bot was detected. good - events where a good bot was detected. bad - events where a bad bot was detected. none - events where no bot was detected.

Note: When using this parameter, only events with the bot property set to a valid value are returned. Events without a bot Smart Signal result are left out of the response.

Available options: all, good, bad, none

bot_info · enum<string>

Filter events by their Bot Info result, specifically:

• all - events where any kind of bot was detected.
• none - events where no bot was detected.

Available options: all, none

bot_info_category · enum<string>[]

Filter events by their Bot Info Category.

Multiple categories can be provided using the repeated keys syntax. For example, bot_info_category=ai_agent&bot_info_category=ai_assistant, will match events with a Bot Info Category of ai_agent or ai_assistant. Other notations like comma-separated or bracket notation are not supported.

The type and purpose of the bot.

Available options: advertising_and_marketing, aggregator, ai_agent, ai_assistant, ai_browser, ai_crawler, ai_search, browser_automation, ecommerce, monitoring_and_analytics, other, scraping, security, search_engine_crawler, search_engine_optimization, unknown

bot_info_identity · enum<string>[]

Filter events by their Bot Info Identity type.

Multiple identity types can be provided using the repeated keys syntax. For example, bot_info_identity=verified&bot_info_identity=signed, will match events with a Bot Info Identity of verified or signed. Other notations like comma-separated or bracket notation are not supported.

The verification status of the bot's identity:

• verified - well-known bot with publicly verifiable identity, directed by the bot provider.
• signed - bot that signs its platform via Web Bot Auth, directed by the bot provider's customers.
• spoofed - bot that claims a public identity but fails verification.
• unknown - bot that does not publish a verifiable identity.

Available options: verified, signed, spoofed, unknown

bot_info_confidence · enum<string>[]

Filter events by their Bot Info Confidence.

Multiple confidences can be provided using the repeated keys syntax. For example, bot_info_confidence=high&bot_info_confidence=medium, will match events with a Bot Info Confidence of high or medium. Other notations like comma-separated or bracket notation are not supported.

Confidence level of the bot identification.

Available options: low, medium, high

bot_info_provider · string[]

Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported.

Multiple Providers can be provided using the repeated keys syntax. For example, bot_info_provider=OpenAI&bot_info_provider=AWS, will match events with a Bot Info Provider of OpenAI or AWS. Other notations like comma-separated or bracket notation are not supported.

bot_info_name · string[]

Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported.

Multiple Names can be provided using the repeated keys syntax. For example, bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore, will match events with a Bot Info Name of ChatGPT Agent or Bedrock AgentCore. Other notations like comma-separated or bracket notation are not supported.

ip_address · string

Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32

asn · string

Filter events by the ASN associated with the event's IP address. This corresponds to the ip_info.(v4|v6).asn property in the response.

linked_id · string

Filter events by your custom identifier.

You can use linked Ids to associate identification requests with your own identifier, for example, session Id, purchase Id, or transaction Id. You can then use this linked_id parameter to retrieve all events associated with your custom identifier.

url · string

Filter events by the URL (url property) associated with the event.

bundle_id · string

Filter events by the Bundle ID (iOS) associated with the event.

package_name · string

Filter events by the Package Name (Android) associated with the event.

origin · string

Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com)

start · integer<int64> string<date-time>

Include events that happened after this point (with timestamp greater than or equal the provided start Unix milliseconds value or RFC3339 timestamp). Defaults to 7 days ago. Setting start does not change end's default of now — adjust it separately if needed.

Example:

1767225600000

end · integer<int64> string<date-time>

Include events that happened before this point (with timestamp less than or equal the provided end Unix milliseconds value or RFC3339 timestamp). Defaults to now. Setting end does not change start's default of 7 days ago — adjust it separately if needed.

Example:

1769903999000

reverse · boolean

When true, sort events oldest first (ascending timestamp order). Defaults to false (newest first, descending timestamp order).

suspect · boolean

Filter events previously tagged as suspicious via the Update API.

Note: When using this parameter, only events with the suspect property explicitly set to true or false are returned. Events with undefined suspect property are left out of the response.

vpn · boolean

Filter events by VPN Detection result.

Note: When using this parameter, only events with the vpn property set to true or false are returned. Events without a vpn Smart Signal result are left out of the response.

virtual_machine · boolean

Filter events by Virtual Machine Detection result.

Note: When using this parameter, only events with the virtual_machine property set to true or false are returned. Events without a virtual_machine Smart Signal result are left out of the response.

tampering · boolean

Filter events by Browser Tampering Detection result.

Note: When using this parameter, only events with the tampering.result property set to true or false are returned. Events without a tampering Smart Signal result are left out of the response.

anti_detect_browser · boolean

Filter events by Anti-detect Browser Detection result.

Note: When using this parameter, only events with the tampering.anti_detect_browser property set to true or false are returned. Events without a tampering Smart Signal result are left out of the response.

incognito · boolean

Filter events by Browser Incognito Detection result.

Note: When using this parameter, only events with the incognito property set to true or false are returned. Events without an incognito Smart Signal result are left out of the response.

privacy_settings · boolean

Filter events by Privacy Settings Detection result.

Note: When using this parameter, only events with the privacy_settings property set to true or false are returned. Events without a privacy_settings Smart Signal result are left out of the response.

jailbroken · boolean

Filter events by Jailbroken Device Detection result.

Note: When using this parameter, only events with the jailbroken property set to true or false are returned. Events without a jailbroken Smart Signal result are left out of the response.

frida · boolean

Filter events by Frida Detection result.

Note: When using this parameter, only events with the frida property set to true or false are returned. Events without a frida Smart Signal result are left out of the response.

factory_reset · boolean

Filter events by Factory Reset Detection result.

Note: When using this parameter, only events with a factory_reset time. Events without a factory_reset Smart Signal result are left out of the response.

cloned_app · boolean

Filter events by Cloned App Detection result.

Note: When using this parameter, only events with the cloned_app property set to true or false are returned. Events without a cloned_app Smart Signal result are left out of the response.

emulator · boolean

Filter events by Android Emulator Detection result.

Note: When using this parameter, only events with the emulator property set to true or false are returned. Events without an emulator Smart Signal result are left out of the response.

root_apps · boolean

Filter events by Rooted Device Detection result.

Note: When using this parameter, only events with the root_apps property set to true or false are returned. Events without a root_apps Smart Signal result are left out of the response.

vpn_confidence · enum<string>

Filter events by VPN Detection result confidence level. high - events with high VPN Detection confidence. medium - events with medium VPN Detection confidence. low - events with low VPN Detection confidence.

Note: When using this parameter, only events with the vpn.confidence property set to a valid value are returned. Events without a vpn Smart Signal result are left out of the response.

Available options: high, medium, low

min_suspect_score · number<float>

Filter events with Suspect Score result above a provided minimum threshold.

Note: When using this parameter, only events where the suspect_score property set to a value exceeding your threshold are returned. Events without a suspect_score Smart Signal result are left out of the response.

developer_tools · boolean

Filter events by Developer Tools detection result.

Note: When using this parameter, only events with the developer_tools property set to true or false are returned. Events without a developer_tools Smart Signal result are left out of the response.

location_spoofing · boolean

Filter events by Location Spoofing detection result.

Note: When using this parameter, only events with the location_spoofing property set to true or false are returned. Events without a location_spoofing Smart Signal result are left out of the response.

mitm_attack · boolean

Filter events by MITM (Man-in-the-Middle) Attack detection result.

Note: When using this parameter, only events with the mitm_attack property set to true or false are returned. Events without a mitm_attack Smart Signal result are left out of the response.

rare_device · boolean

Filter events by Device Rarity detection result.

Note: When using this parameter, only events with the rare_device property set to true or false are returned. Events without a Device Rarity Smart Signal result are left out of the response.

This Smart Signal is currently in beta and only available to select customers. If you are interested, please contact our support team.

rare_device_percentile_bucket · enum<string>

Filter events by Device Rarity percentile bucket. <p95 - device configuration is in the bottom 95% (most common). p95-p99 - device is in the 95th to 99th percentile. p99-p99.5 - device is in the 99th to 99.5th percentile. p99.5-p99.9 - device is in the 99.5th to 99.9th percentile. p99.9+ - device is in the top 0.1% (rarest). not_seen - device configuration has never been observed before.

This Smart Signal is currently in beta and only available to select customers. If you are interested, please contact our support team.

Available options: <p95, p95-p99, p99-p99.5, p99.5-p99.9, p99.9+, not_seen

proxy · boolean

Filter events by Proxy detection result.

Note: When using this parameter, only events with the proxy property set to true or false are returned. Events without a proxy Smart Signal result are left out of the response.

sdk_version · string

Filter events by a specific SDK version associated with the identification event (sdk.version property). Example: 3.11.14

sdk_platform · enum<string>

Filter events by the SDK Platform associated with the identification event (sdk.platform property) . js - Javascript agent (Web). ios - Apple iOS based devices. android - Android based devices.

Available options: js, android, ios

environment · string[]

Filter for events by providing one or more environment IDs (environment_id property).

Array syntax

To provide multiple environment IDs, use the repeated keys syntax (environment=env1&environment=env2). Other notations like comma-separated (environment=env1,env2) or bracket notation (environment[]=env1&environment[]=env2) are not supported.

proximity_id · string

Filter events by the most precise Proximity ID provided by default.

Note: When using this parameter, only events with the proximity.id property matching the provided ID are returned. Events without a proximity result are left out of the response.

total_hits · integer<int64>

When set, the response will include a total_hits property with a count of total query matches across all pages, up to the specified limit.

Required range: 1 <= x <= 1000

tor_node · boolean

Filter events by Tor Node detection result.

Note: When using this parameter, only events with the tor_node property set to true or false are returned. Events without a tor_node detection result are left out of the response.

incremental_identification_status · enum<string>

Filter events by their incremental identification status (incremental_identification_status property). Non incremental identification events are left out of the response.

Available options: partially_completed, completed

simulator · boolean

Filter events by iOS Simulator Detection result.

Note: When using this parameter, only events with the simulator property set to true or false are returned. Events without a simulator Smart Signal result are left out of the response.

Response

200

application/json

Events matching the filter(s).

Contains a list of all identification events matching the specified search criteria.

events · object[] · required

Show child attributes

pagination_key · string

Use this value in the pagination_key parameter to request the next page of search results.

total_hits · integer<int64>

This value represents the total number of events matching the search query, up to the limit provided in the total_hits query parameter. Only present if the total_hits query parameter was provided.