If you've deployed an AI endpoint on Vercel, you've probably wondered how to keep abusers from hammering your API and draining your inference budget. The platform's new BotID feature offers a clean solution: it verifies that each request originates from a real browser before any model ever gets invoked, acting as an invisible CAPTCHA that runs silently alongside your existing routes.

How Vercel BotID Works

BotID operates in two phases. First, it attaches client-side challenge headers to requests on the routes you declare during initialization using initBotId(). Then, inside your server route handler, checkBotId() reads those headers and classifies each request as legitimate or bot traffic. The beauty here is that verification happens per-request rather than once per session, so an attacker can't bypass it one time and reuse that access across thousands of calls. If the check fails, the request never reaches your model—meaning you don't pay for tokens you didn't want to spend.

A Four-Step Setup

Getting started requires four steps. First, install the botid package into your project. Second, wrap your framework config with withBotId to set up proxy rewrites that prevent ad-blockers and third-party scripts from weakening protection. For Next.js 15.3 and later, create an instrumentation-client.ts file and call initBotId() there, passing in a protect array that lists the AI routes you want guarded. Finally, call checkBotId() inside your route handler before runInference executes—keeping this order is crucial since blocked requests never trigger the model.

Choosing Your Detection Level

Basic validation runs free on all plans and catches many unsophisticated bots. But for high-value endpoints, Deep Analysis taps into a Kasada-powered machine learning model that reads thousands of client-side signals to identify coordinated attacks even when traffic initially looks legitimate. One documented incident traced a 500% traffic spike back to a bot network by correlating identical browser fingerprints cycling through proxy nodes—Deep Analysis reclassified and blocked those sessions within about ten minutes without manual intervention. This feature requires Pro or Enterprise, and you're only charged for requests that actually invoke checkBotId(), not passive page views.

Letting Verified Bots Through

Blocking based on isBot alone catches everything automated, including helpful crawlers like Googlebot and AI assistants such as ChatGPT Operator. If you want to allow specific agents while still blocking everything else, check the verified-bot fields that checkBotId() returns alongside its classification: look for isVerifiedBot, verifiedBotName, and verifiedBotCategory in your handler logic. For trusted services not yet in Vercel's verified bot directory, add a WAF bypass rule rather than stripping protection from the route entirely.

Testing Protected Routes

Here's an important gotcha: BotID runs JavaScript inside browser sessions to generate challenge headers, so a direct curl request or URL typed into your address bar will always be flagged as bot traffic in production. To test protected routes, make fetch calls from within your own application instead. In local development, requests return isBot: false unless you configure the developmentOptions option—check Vercel's docs for instructions on simulating bot behavior during testing.

Key Takeaways

  • Keep checkBotId() ahead of runInference in your handler so blocked requests never cost tokens
  • Use advancedOptions.checkLevel to apply deepAnalysis only where needed, saving costs elsewhere
  • Match your client and server route declarations exactly or verification will silently fail
  • Test from within your app rather than curl when working locally

The Bottom Line

Vercel BotID fills a real gap for teams running AI endpoints at scale—it's refreshingly straightforward to implement and the per-request verification model is genuinely more robust than session-based alternatives. If you're tired of watching your inference costs spike from automated abuse, this tutorial makes it easy to lock things down without adding friction for legitimate users.