Bot protection: forms, crawlers and rules

Bot protection works on the website picked in the header switcher, and only on verified websites. Open Dashboard → Bot protection, switch it on, add the script and check tokens on your server. Real visitors never see a puzzle.

1. Add the script

Add <script src="https://serpfull.com/b/v1.js" data-site="YOUR_SITE_KEY" async></script> to pages with forms and add data-serpfull-protect to each form, or choose "Every form on the page" in settings. While the visitor fills in the form, their browser solves a small proof-of-work challenge in the background and the form gets a serpfull-bot-token field when it's sent. The script is about 3.5 KB compressed, sets no cookies and stores nothing on the device. A short status line under the form is announced to screen readers; add data-status="off" to hide it.

2. Check the token on your server

Before accepting the form, POST JSON { secret, token } to https://serpfull.com/api/b/verify. Add email, name, message and honeypot (the sf_hp field) to get a spam score as well. The answer is { success, score, reasons, spam }. Tokens work once and expire after five minutes; a reused, forged or expired token returns success: false. Keep your secret on your server only. Rotating it in Keys and settings keeps the old secret working for 24 hours.

Scores and reasons

• score runs from 0 (a person) to 100 (a bot). The browser check rejects anything above your threshold: 80 on Relaxed, 60 on Balanced, 40 on Strict.
• Signals include browser automation flags, headless browsers, a filled hidden field, no typing or pointer use, a form filled in too fast and a challenge solved impossibly fast.
• spam.score adds throwaway email domains, links and link markup, common spam wording, all-capitals text, repeated characters and suspicious names. You decide what to do with it, for example hold messages over 50 for review.

Search engine crawlers

Requests that claim to come from a major search engine or AI search crawler are confirmed with a reverse and forward network address lookup. Verified crawlers are let through; fakes using their name are blocked and logged as fake crawlers.

Rules

Rules match country, network (ASN), browser user agent, IP address or range, page path, crawler status or bot score, and either block, check first, limit requests per minute per visitor, or always allow. They're checked top to bottom and the first match wins. Rules apply to page checks and form checks.

Whole-page protection (optional)

The Next.js middleware and Express guides in Dashboard → Bot protection → Install send each request's IP, user agent and path to https://serpfull.com/api/b/check with your secret. The answer is allow, challenge or block and how long to cache it. A challenge shows a small check page that solves the same invisible challenge and then sets one strictly necessary security cookie (sf_bot) for 30 minutes. If our check can't be reached, the snippets let the visitor through.

Works with Serpfull SERP clicks

Whole-page protection recognises Serpfull's own SERP click runs and lets them through, so your click runs keep reaching your site while bad bots are still blocked. Each click run carries a signed pass that is tied to your website and to that run, and expires within minutes; our servers check it when your middleware asks, so it can't be copied or faked. Pass the x-serpfull-click request header to the check as click (the install guides already do). Nothing else to set up.

Analytics

Bot, crawler and automated visits are detected by our analytics and kept out of your visitor numbers. They're counted as bot visits on the Bot protection overview.

Alerts

When failed, blocked, spam or fake-crawler requests in an hour reach at least 50 and three times the usual hourly level, your team gets an email and an in-app notification, and the bot.attack.detected webhook fires. Turn alerts off in Keys and settings.

Limits

• Form checks per website per month: 50,000 on Starter, 250,000 on Growth, 1 million on Scale, 10 million on Pro, 30 million on Enterprise.
• Page checks per month: 250,000, 1 million, 5 million, 15 million, 50 million and 150 million.
• Rules: 10, 25, 50, 100, 250 and 500. Events kept for 7, 14, 30, 30, 60 and 90 days.
• Over the limit, forms keep working: checks pause until next month and the verify answer says success with score null and quota_exceeded true.

Take the guided tour

In the dashboard, click the wand icon in the header and choose “Bot protection”, or pick “Tour this page” while you’re on it. The tour highlights each part of the page step by step.