Frequently Asked Questions
Answers to the most common questions about PerfectSearch. Can't find what you're looking for? Check the full documentation or contact support.
General
What is PerfectSearch?
PerfectSearch is a pre-rendering service that makes JavaScript websites fully visible to search engine bots and AI crawlers. It serves pre-rendered HTML and Markdown snapshots to bots while human visitors see your normal site. This ensures that Googlebot, GPTBot, ClaudeBot, and other crawlers can index and cite your content accurately.
Do I need to change my code?
For Next.js, you add a middleware file which takes about 2 minutes. For any other framework, use DNS proxy mode with zero code changes — just update a DNS record. Both integration modes deliver the same pre-rendering capabilities with no changes to your application code or build process.
Which bots does PerfectSearch support?
All major search engines including Googlebot, Bingbot, and DuckDuckBot, plus AI crawlers such as GPTBot, ChatGPT-User, ClaudeBot, Claude-Web, PerplexityBot, Applebot-Extended, anthropic-ai, Google-Extended, Bytespider, CCBot, cohere-ai, and meta-externalagent. The full list is available in the AI Crawlers documentation.
Does PerfectSearch affect my site's performance?
No. Human visitors never interact with PerfectSearch. Only bot traffic is intercepted and served pre-rendered snapshots. Middleware mode adds less than 5 milliseconds of overhead per request. DNS proxy mode adds less than 10 milliseconds. Your site's Core Web Vitals and user experience remain completely unaffected.
Is PerfectSearch compatible with my framework?
Yes. Middleware mode works with Next.js 14 and 15 using App Router or Pages Router. DNS proxy mode works with any JavaScript framework including Nuxt, SvelteKit, Remix, Astro, Hydrogen, Vite, Create React App, Angular, and static site generators. If your site runs on the web, PerfectSearch can pre-render it.
Setup
How long does setup take?
Under 5 minutes for either integration mode. Middleware mode requires installing a package and adding a middleware.ts file. DNS proxy mode requires adding a CNAME record and configuring your origin URL in the dashboard. Both modes are production-ready immediately after setup.
Can I use PerfectSearch with Shopify?
Yes. For Shopify Hydrogen storefronts, use DNS proxy mode with your Oxygen deployment URL as the origin. See the Shopify quickstart guide for step-by-step instructions. Traditional Shopify stores using Liquid templates typically do not need pre-rendering since Liquid renders server-side by default.
What happens if PerfectSearch goes down?
In middleware mode, the middleware falls back to serving your normal site without pre-rendering. Your site stays up with no downtime — bots simply see the regular JavaScript-rendered page. In DNS proxy mode, traffic continues to be proxied to your origin server. Bots see your original JavaScript content until service is restored.
Can I use both middleware and DNS proxy?
No, choose one integration mode per site. Use middleware mode for Next.js applications where you want edge-level bot detection. Use DNS proxy mode for everything else, or when you want zero code changes. Both modes deliver the same snapshot quality and bot detection accuracy.
How do I test if PerfectSearch is working?
Use the free visibility test tool at /tools/visibility-test. It checks your URL against all major search engine and AI crawlers, showing you exactly what each bot sees when it visits your page. The tool displays the rendered content, response headers, and any issues detected.
Features
Can I block specific AI crawlers?
Yes. Use access control rules in the dashboard to block training crawlers like GPTBot while allowing retrieval crawlers like ChatGPT-User that help your AI visibility. Pre-built presets make this easy: the block-training preset blocks all training crawlers with one click while keeping retrieval crawlers active.
What is the difference between HTML and Markdown snapshots?
HTML snapshots are served to search engine bots like Googlebot for indexing. Markdown snapshots are served to AI and LLM bots like ChatGPT-User and ClaudeBot for cleaner content ingestion. PerfectSearch auto-detects the bot type and serves the right format automatically, so you don't need to configure anything.
How do I connect Google Search Console?
Go to Dashboard, then Settings, then the GSC section, and click Connect. Authorize with your Google account and select your search property. Once connected, you can see search performance data alongside your bot traffic analytics. Google Search Console integration is available on Growth plan and above.
Can I see what bots are visiting my site?
Yes. The dashboard shows real-time bot request analytics including which bots are visiting, how many requests each makes, your top crawled pages, and traffic trends over time. The AI Crawlers tab provides a detailed breakdown of training vs. retrieval crawler activity across your site.
How fresh are the snapshots?
Default cache TTL is 24 hours. When a snapshot is stale, PerfectSearch serves the stale version to the bot immediately while re-rendering the page in the background using a stale-while-revalidate strategy. This means bots always get a fast response, and the cache stays fresh with minimal rendering overhead.
Billing
How much does PerfectSearch cost?
Plans start at free with a 14-day trial including 10,000 bot requests. Paid plans are Starter at $19 per month with 100,000 requests, Growth at $79 per month with 1,000,000 requests, and Scale at $249 per month with 10,000,000 requests. Overage beyond your plan limit is billed at $0.10 per 1,000 requests.
What counts toward my usage?
Each bot request that PerfectSearch serves counts as one request, whether it is a cache hit or a cache miss. Human traffic and requests blocked by access control rules do not count toward your usage. Only requests where a snapshot is actually served to a detected bot are metered.
Is there a free trial?
Yes. The free trial lasts 14 days and includes 10,000 bot requests with one site. No credit card is required to start. You get full access to core features including bot detection, pre-rendering, and the basic dashboard. When the trial ends, upgrade to a paid plan to continue service.
Can I cancel anytime?
Yes. Cancel your subscription from Dashboard, then Billing, or contact support. Service continues until the end of your current billing period. After cancellation, your sites stop receiving pre-rendered snapshots and bots see your regular JavaScript-rendered pages instead.
Do I get charged for overages?
Yes, at $0.10 per 1,000 requests beyond your plan limit. Service is never interrupted when you exceed your limit. Overage charges are calculated at the end of your billing cycle and added to your next invoice. You can monitor your usage in real-time on the Billing page to avoid unexpected charges.
Troubleshooting
Bots are still seeing empty pages after setup. What do I do?
Check three things in order: 1) Verify the middleware matcher covers the path in your middleware.ts file. 2) Check if a snapshot exists in Dashboard under the Snapshots tab for that path. 3) Use the bot view tool at /tools/bot-view to see exactly what bots receive. See the debugging guide for a complete troubleshooting checklist.
I'm getting ERR_TOO_MANY_REDIRECTS with DNS proxy. How do I fix it?
Your origin URL is redirecting back to the proxy domain, creating an infinite redirect loop. In the PerfectSearch dashboard, update your origin URL to the non-proxied domain — for example, use your .vercel.app or .netlify.app URL instead of your custom domain that is CNAMEd to PerfectSearch.
My cache hit rate is very low. Is that normal?
For new sites, yes — the cache builds up over time as bots visit pages and snapshots are generated. To pre-warm your cache, use POST /v1/snapshot/queue to queue your most important pages for rendering, or add your sitemap URL in the dashboard to trigger an initial crawl of all pages.
Vercel is showing a 'Verifying your browser' page to bots. What do I do?
Configure a Vercel Deployment Protection bypass secret. Go to your Vercel project settings, enable Protection Bypass for Automation, copy the generated secret, and paste it in PerfectSearch dashboard under your site Settings. See the Vercel bypass guide for detailed step-by-step instructions.
How do I invalidate all cached snapshots?
Two options: In the dashboard, navigate to your site, then Settings, then click the Purge All Cache button. Or use the API by sending POST /v1/webhook/invalidate with the pattern "/**" to invalidate all paths. For targeted invalidation, use a specific pattern like "/blog/**" to only clear matching paths.
Need more help?
If your question is not answered here, check the detailed debugging guide for troubleshooting, or reach out to our support team at support@perfectline.io.