Troubleshooting Unexpected Usage Spikes

If you're seeing a sudden spike in Fingerprint usage, it usually comes down to two main causes: implementation issues or malicious traffic. This guide will help you quickly diagnose and resolve the issue.

Quick Checklist

• Check for recent code changes - Spikes often correlate with a recent deployment. Review any updates that may have changed when or where the Fingerprint agent is called.
• Check for caching - Without caching, repeat visits or user actions can trigger multiple identification requests. Ensure visitor IDs are cached appropriately using sessionStorage or localStorage.
• Audit for duplicate calls - Look for React useEffect calls missing dependency arrays, or code that triggers get() multiple times per session.
  • The JavaScript SDK only bills for get() calls. Confirm you’re calling it only when the visitorId is needed, and not on every page load or render.
• Review the "Insights" section - On the Overview page of your Fingerprint dashboard, adjust the trend chart by selecting the "events per visitor" metric in the drop down. A noticeable increase could indicate your code is sending more identification requests than before.
• Inspect Smart Signals - Use the Smart Signals page to check for bot activity. Spikes caused by "bad bots" suggest abuse, not implementation error.
• Secure your API key - Check if your API key is used on unknown domains or apps. Set up request filtering to block unwanted domains, headers, or IPs.
• Contact support - If you’re still unsure, reach out to Support or review our bill forgiveness policy.

Implementation Related Spike

These spikes are usually caused by integration issues. Clues include a spike following a recent code change or usage increasing alongside user activity. For example, if usage scales with traffic but seems higher than expected, it may indicate an implementation issue - such as more identification calls per user than intended. Common causes include missing caching, duplicate calls, or unintentional triggers.

Missing Visitor ID Caching

• Without caching your visitorId, each page load or user action can generate a new request, increasing your API usage.
• Choosing whether to cache depends on your use case and risk tolerance:
  • If your use case demands highly accurate identification, we recommend identifying the visitor on demand and always using a fresh visitor ID without caching.
  • For less sensitive scenarios, caching can significantly reduce redundant calls and improve performance.
• You can store the visitorId in sessionStorage (recommended) or localStorage to reuse the ID for up to 1 hour and reduce redundant calls.

Read: Caching Visitor ID

Duplicate Calls from Loops

• Common in single-page applications (SPAs) where component re-renders or navigation triggers extra calls.
• In React, missing a dependency array in useEffect can cause get() to be called on every render.
• Use the React SDK to manage this more easily.

Unintended Calls to Fingerprint

• For the JavaScript SDK, load() requests are not billed, but get() requests are.
  • Only call get() when the visitorId will be used by your application.
• Avoid triggering identification on every render or page view.
• Visit the Optimizing JavaScript Agent Usage page to learn more about common use cases and when to make the get() request.

Malicious Traffic or Bot-Driven Spike

These spikes often happen suddenly and without any recent deployments. Look for unusual traffic patterns - like bursts of activity or off-hour usage. Use Smart Signals or the Server API to review recent identification events. A high number of “bad bot” detections typically points to automated abuse, not an integration issue.

Bot Traffic

• Visit the Smart Signals - Bot detection page to view traffic flagged as bots.
• A sudden increase in "bad bots" can indicate scraping or automated abuse.
• Use this information to adjust filters or rate-limiting rules in your app.

Some helpful resources to learn more:

• Browser Bot detection
• Bot detection: How to block bad bots in 2025
• How to Identify and Block Bots in Your Firewall
• Mitigating bad bots at WAF level through Cloudflare

Public API Key Misuse

• Public API keys are visible in client-side code and can potentially be leaked or copied.
• Check whether your API key is being used on unknown domains or in unauthorized mobile apps.
• It’s good practice to restrict your API key to only the domains, headers, or IP addresses where legitimate traffic is expected.
• Set up Request Filtering in the dashboard to prevent unwanted usage and protect your billing.

Protect your Public API key:

• Request Filtering for Websites
• Mobile App Filtering
• Search Bot Filtering
• Network Filtering

Deep Dive: Exporting and Analyzing Identification Data

If you want to dig deeper into a spike, exporting your data to CSV allows for a more granular investigation. Here's how:

1. Check usage trends - Go to the Overview page and review API usage over the past 30 days.
2. Identify the spike window - Pinpoint the spike date, and include the day before and after.
3. Filter identification events - Navigate to the Identification page and apply a date filter for that window.
4. Export the data - Use the export option to download a CSV file of events.
5. Analyze usage patterns - Use the CSV to review the data grouped by:
   • visitorId
   • linkedId or tag
   • url
   • ipLocation.country.name

This can help surface unusual usage patterns, like excessive requests from a single user or unexpected geographies.

Next Steps and Support

• If you can’t resolve the issue on your own, please reach out to support.
• You may be eligible for partial bill forgiveness in cases of unintentional spikes or confirmed malicious activity.

Important: Forgiveness can only be applied to your most recent completed invoice (i.e. the last completed billing cycle). Older invoices are not eligible, even if they experienced a spike.