FAQ

Frequently asked questions

Quick answers to the questions developers ask most, from your first request to billing, webhooks, and result pagination.

1. How do I authenticate and make my first API request?

Send your API key as a Bearer token in the Authorization header, or pass api_token=<YOUR_API_KEY> as a query string, on every request. Sign up at serphouse.com, confirm your email, and copy the key from your dashboard, then send your first POST to https://api.serphouse.com/serp/live.

1. Register at serphouse.com and confirm the email link sent to your inbox. Only one account is allowed per user; if you need extra testing credits, contact support instead of creating duplicates.

2. Get your API key. It appears on your account dashboard once your email is confirmed. Keep it secret and never commit it to public scripts.

3. Authenticate. Send your key as a Bearer token in the Authorization header of every request, or pass api_token=<YOUR_API_KEY> as a query string:

POST /serp/live HTTP/1.1
Host: api.serphouse.com
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

4. Minimal live request:

curl -X POST "https://api.serphouse.com/serp/live" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"q": "coffee", "domain": "google.com", "lang": "en", "device": "desktop", "serp_type": "web", "loc": "Alba,Texas,United States"}'

See Getting Started and Live (HTTP POST) for full field tables.

2. Where are the correct endpoints, payload fields, documentation, and code examples?

Everything lives in this docs site: endpoint references under Getting Started, Google, Bing, and Yahoo; required fields are marked with an asterisk on every page; and interactive examples are included per endpoint plus Node.js, PHP, and Python SDKs.

• Endpoints: Getting Started, Google, Bing, Yahoo, Extra APIs
• Fields: every page documents required parameters (marked with an asterisk) and shows sample responses
• Examples: interactive snippets per page, plus Node.js, PHP, and Python SDKs

3. How do credits, trial allowances, plans, request limits, and custom pricing work?

Credits are charged only on successful responses; failed requests, retries, and blocks are free. The Free plan is $0/month with 4,000 credits, Basic is $29.99/month with 400,000, and Regular is $49.99/month with 800,000; all standard plans allow 60 req/min, and running out of credits returns a 402.

• Rate limit is 60 req/min on Free, Basic, and Regular plans (Custom scales as needed)
• Credits do not roll over month to month
• Running out of credits returns a 402 response
• Custom plans scale credits, rate limits, and pricing to your volume; contact support
• Check usage anytime with Account Info

4. What is the difference between live, delayed, and scheduled requests?

Live requests are synchronous and return results in the same HTTP response, best for dashboards and single lookups. Scheduled (delayed) requests are asynchronous: submit with POST /serp/schedule, poll Check SERP Status, and fetch with Get SERP Result; each batch supports up to 100 keywords.

• Live: synchronous. Results come back in the same HTTP response. Best for dashboards and single lookups (available over GET & POST).
• Scheduled / delayed: asynchronous. Submit with POST /serp/schedule, then poll Check SERP Status and fetch with Get SERP Result.
• Batch: up to 100 keywords per scheduled request, optionally delivering via postback_url / pingback_url.

Full comparison: About SERPHouse.

5. How long do delayed requests take, and how do webhooks, postbacks, or pingbacks work?

Delayed jobs complete as capacity allows, with no fixed SLA, so use notifications instead of polling: pingbacks send an HTTP GET to your pingback_url when results are ready, postbacks POST the JSON results to your postback_url, and webhooks are configured on the Webhook page with automatic retries. Every payload is signed with HMAC-SHA256 in the x-serphouse-signature header.

• Pingback: an HTTP GET to your pingback_url when results are ready (then fetch them with Get SERP Result)
• Postback: an HTTP POST with JSON results to your postback_url
• Webhooks: configure on the Webhook page, with retries at 0s, 100s, 1,000s, and 1,800s (4 failures = permanent fail)

If your server doesn't respond within 5 seconds the delivery is treated as failed and resent.

Payloads are signed with HMAC-SHA256 in the x-serphouse-signature header. Validate it to confirm the request really came from SERPHouse.

6. Why did my request time out, return an error, produce empty results, or remain stuck?

Match the HTTP status code: 200 is success, 400 an invalid body, 401 a bad or missing API key, 402 insufficient credits, 404 an invalid SERP ID or endpoint, 429 a rate limit, and 500 a server error. A 200 with "msg": "Please try again" is a momentary failure; just retry after a short wait. For scheduled tasks, poll /serp/check until status is Completed, then fetch with /serp/get.

• Scheduled tasks: poll /serp/check until status is Completed, then call /serp/get to fetch results
• Empty results usually mean the task is still processing or the engine returned nothing
• If a task id seems stuck, re-check after a few minutes before contacting support
• Permanently-failed webhooks can always be fetched manually with the Get SERP Result API

7. How many results are returned, how does pagination work, and why can image, news, shopping, or other result types behave differently?

Live requests return up to 10 results per page, and you paginate with the page parameter, where each page is a separate request. The Google Top 100 endpoint fetches up to 100 results across pages with max_pages. The serp_type parameter (web, news, image, shop) shapes which fields each result exposes, so the response structure varies by type.

• Live / single-request: default 10 results per page, maximum num_result is 10
• Pagination: use the page parameter (1, 2, …), each page is a separate request
• Top 100: the Google Top 100 endpoint fetches up to 100 results across pages with max_pages (1 page ≈ 10 results, each page costs 10 credits)
• serp_type shapes the response:
  • web: organic results, ads, knowledge panels, related searches
  • news: source and published date
  • image: image URLs and thumbnails
  • shop: price, rating, and shop
• Different result types expose different fields, so the response shape varies by serp_type; likewise verbatim, gfilter, and date_range affect what comes back

API and data

1. Which search engines and domains do you support?

SERPHouse supports Google (google.com plus per-country domains like google.co.uk and google.ca), Bing (bing.com), and Yahoo (regional domains such as uk.yahoo.com). Browse the full list on the Domains List page or query GET /domain/list at runtime.

• Google: google.com plus per-country domains (google.co.uk, google.ca, google.co.in, …)
• Bing: bing.com
• Yahoo: regional domains such as uk.yahoo.com
• Browse every supported domain on the Domains List page or query the GET /domain/list endpoint at runtime

2. What format do API responses come in?

JSON is the default: a successful 200 response returns the SERP data in the results field. Many endpoints also support Markdown and HTML by appending a suffix to the endpoint URL: /md for Markdown and /html for HTML (no suffix returns JSON), for example https://api.serphouse.com/google-web/md.

• JSON is the default; a successful 200 response returns the SERP data in the results field
• Some endpoints also support HTML and Markdown; append a suffix to the endpoint URL to pick the format: /md for Markdown and /html for HTML (no suffix returns JSON)
  • For example: https://api.serphouse.com/google-web → JSON, https://api.serphouse.com/google-web/md → Markdown, https://api.serphouse.com/google-web/html → HTML
• Live requests over GET & POST accept all three formats; most other endpoints accept html or json
• The fields inside results vary by serp_type; each endpoint page shows a sample response

3. Can I try the API for free?

Yes. The Free plan is $0/month and includes 4,000 API credits, and failed requests, retries, and blocks are never charged. Track your remaining credits anytime with Account Info.

• Yes: the Free plan is $0/month and includes 4,000 API credits
• Failed requests, retries, and blocks are never charged
• Track remaining credits anytime with Account Info

4. How fast are live requests?

Live requests are synchronous and typically return results within seconds in the same HTTP response. Scheduled jobs run through a queue and complete as capacity allows, so use webhooks or pingbacks to be notified the moment results are ready.

• Live requests are synchronous; results come back in the same HTTP response, typically within seconds
• Scheduled jobs run through a queue and complete as capacity allows (no fixed SLA). Use webhooks or pingbacks to be notified the moment results are ready

5. Can I run bulk or batch queries?

Yes. Up to 100 keywords per scheduled request, with optional postback_url / pingback_url delivery straight to your server. For deep SERPs, the Google Top 100 endpoint returns up to 100 results per query via max_pages.

• Yes: up to 100 keywords per scheduled request
• Deliver results straight to your server with postback_url / pingback_url
• For deep SERPs, the Google Top 100 endpoint returns up to 100 results via max_pages

6. Do I need proxies or CAPTCHA solving?

No. SERPHouse manages the proxies and handles CAPTCHAs for you. You never solve or forward CAPTCHAs; just send the query and read the results.

• No: SERPHouse manages the proxies and handles CAPTCHAs for you
• You never solve or forward CAPTCHAs; just send the query and read the results

More questions

1. How do I verify my account, retrieve my API key, or resolve signup and CAPTCHA issues?

Click the confirmation link emailed after signup at serphouse.com, and your API key appears on the dashboard once your email is confirmed. CAPTCHAs are handled entirely by SERPHouse; you never solve or forward them. No email? Check spam, then contact support.

• Verify: click the confirmation link emailed after signup at serphouse.com
• API key: shown on your dashboard once your email is confirmed
• One account per user: request extra testing credits from support instead of creating duplicates
• CAPTCHAs: handled entirely by SERPHouse; you never solve or forward them
• No email? Check spam, then contact support

2. How do I update payment details, obtain invoices, or add tax/VAT information?

Manage payment methods, invoices, and tax/VAT information from the billing section of your dashboard; invoices are generated each billing cycle. For tax registration changes, invoice address updates, or custom billing arrangements, contact support.

Manage payment methods, invoices, and tax/VAT information from the billing section of your dashboard. Invoices are generated each billing cycle.

For tax registration changes, invoice address updates, or custom billing arrangements, contact support.

3. How do I cancel or unsubscribe from my subscription?

Cancel anytime from the billing section of your dashboard, and the plan stays active until the end of the current period. After cancelling or downgrading, running out of credits returns a 402; contact support for plan migrations or custom contracts.

Cancel anytime from the billing section of your dashboard; the plan stays active until the end of the current period.

4. Which locations, languages, devices, and search settings are supported?

Pass a location with loc or loc_id (prefer loc_id for stable, machine-readable targeting), language codes such as en or fr, device as desktop or mobile, and settings like verbatim, gfilter, page, num_result, and date_range. Full lists are on the Locations, Languages, and Domains pages.

• Locations: Locations List or the CSV files (Google, Bing). Pass loc or loc_id.

• Languages: Languages List; pass codes like en, fr
• Devices: desktop or mobile
• Domains: Domains List for Google, Bing, and Yahoo
• Settings: verbatim, gfilter, page, num_result, date_range (h/d/w/m/y or YYYY-MM-DD,YYYY-MM-DD)

5. Can I connect the API to Google Sheets, spreadsheets, or another export workflow?

Yes, the API is plain HTTP. Use Apps Script + UrlFetchApp with a Bearer header for Google Sheets (IMPORTDATA can't send headers), Excel/Power Query for the live GET endpoint, or pipelines with scheduled tasks, webhooks, and the Node.js, PHP, and Python SDKs.

Yes, the API is plain HTTP:

• Google Sheets: use Apps Script + UrlFetchApp with a Bearer header (IMPORTDATA can't send headers)
• Excel / Power Query: call the live GET endpoint and parse the returned JSON
• Pipelines: scheduled tasks, webhooks, or the SDKs (Node.js, PHP, Python)

Still have questions?