FAQ

Answers to common questions about credits, data accuracy, and how the API works.

Credits & Billing

Do failed API calls cost credits?

No. Credits are reserved when a request starts, but if the upstream data provider returns an error, your credits are automatically refunded. Your balance will reflect the refund. You are never charged for errors.

If you see a high error rate on a specific endpoint, check that your parameters are correct (business names must match Google exactly, locations should use "City, ST" format). You can use location_search (free) to verify location formatting.

How do credits work with cached responses?

Cached responses cost 0 credits. If you make the same request within the cache window, you get the cached result for free. The response will include "cached": true and "credits_used": 0.

What happens to my credits if I cancel my subscription?

Monthly credits (the ones included with your plan) are converted to wallet credits when you cancel. Wallet credits never expire, so you keep the full value.

What's the difference between monthly credits and wallet credits?

Monthly credits come with your subscription plan and reset each billing cycle. Unused monthly credits do not roll over. Wallet credits come from one-time deposits ($5 minimum) and never expire. When you make an API call, monthly credits are used first, then wallet credits.

Can I see my credit usage history?

Yes. Go to Dashboard > Logs to see every API call with the credits charged. Go to Dashboard > Billing to see your overall balance breakdown (monthly vs wallet) and payment history.

What happens if I don't have enough credits for a request?

The request is rejected before any work starts. You'll get a 402 response with your current balance and the number of credits required. No partial charges, no partial results. Either add wallet credits or upgrade your plan to continue.

Data Accuracy

Why don't the results match what I see when I search Google?

This is the most common question we get. Our ranking data uses non-personalized Google search, which is the industry standard for SEO tools. Google personalizes results for every user based on:

• Your physical location and GPS
• Your search history and browsing behavior
• Whether you're signed into Google
• Your device type (mobile vs desktop)

We strip all personalization to give you a neutral, comparable baseline. This is what you want for tracking rankings over time and benchmarking against competitors. But it means if you search "best plumber near me" on your phone while standing next to a plumbing shop, you'll see different results than our API returns.

When should I expect the biggest differences from my own searches?

• When you're physically near the business (GPS proximity bias is strong)
• When you've visited the business's website before (Google remembers)
• When you're on mobile (mobile rankings differ from desktop)
• For "near me" queries (these are heavily location-personalized)

For the most accurate comparison, use Chrome Incognito with location services disabled. That gets closer to what our API returns.

Why do review counts sometimes differ from what Google shows?

Review counts and ratings may lag Google's live display by a few hours. Google continuously processes and filters reviews (removing spam, enforcing policies), so the exact count fluctuates within a small range. Our snapshots are taken at query time.

Why do AI visibility results change between identical queries?

AI model outputs are non-deterministic. ChatGPT, Gemini, and other LLMs can give different answers to the same prompt minutes apart. Our AI visibility endpoints capture point-in-time snapshots. For trend tracking, run the same queries on a regular schedule and compare over time rather than expecting exact reproducibility.

API & Technical

How long do API calls take?

Most endpoints return in 2-6 seconds. Composite endpoints (Local Audit, Reputation Audit, Citation Audit) take 15-60 seconds because they aggregate multiple data sources. Review Velocity and Multi-Platform Reviews take 10-30 seconds. Geogrid scans take 30-90 seconds depending on grid size.

These are normal processing times, not errors. For slow endpoints, the response includes X-Async-Endpoint: true and X-Expected-Duration-Seconds headers so you can plan accordingly.

What's the difference between sandbox and live API keys?

Sandbox keys (sk_test_*) return realistic mock data and charge zero credits. Use them for development, testing, and integration work. Live keys (sk_live_*) hit real data providers and charge credits. Both use the same endpoints and response shapes.

Can I use the API without code?

Yes. Connect our MCP server to Claude, ChatGPT, Cursor, or other AI tools and use natural language instead of code. See the MCP Setup guide for instructions, or check the No-Code Quick Start.

What happens if I exceed my rate limit?

You'll receive a 429 response with a Retry-After header telling you how many seconds to wait. Rate limits are per-second and vary by plan (Free: 5/sec, Pay-As-You-Go: 15/sec, Starter: 20/sec, Agency: 40/sec, Scale: 100/sec). The rate limit resets every second.

Is there a way to test if my API key works?

Call the GET /v1/account/balance endpoint (free, 0 credits). If it returns your balance, your key is valid. If you get a 401, the key is invalid or revoked.

I keep getting "business not found" errors. What's wrong?

Business names must match exactly how they appear on Google Maps, including punctuation and capitalization. If the name is common (e.g., "Joe's Pizza"), include the city to disambiguate. Use the location_search endpoint (free) to verify the location format, and search Google Maps directly to confirm the exact business name.

What is a geogrid scan?

A geogrid scan checks how a business ranks across a geographic area, not just from one point. It creates a grid of search points around a location (5x5, 7x7, or 9x9) within a radius you specify, then checks the business's ranking at each point. The result is a heatmap showing where the business ranks well and where it drops off. Cost is 2 credits per grid point (50 for 5x5, 98 for 7x7, 162 for 9x9). Geogrid scans are async and take 30-90 seconds depending on grid size.