FAQ & Troubleshooting
General
Do I need an SDK?
No. OmniScrape is a plain REST API — any language that can send an HTTP POST works. See Code examples.
Where do I get an API key?
From the dashboard under API Keys. Send it in the X-API-Key header. See Authentication.
Is there a free trial?
Yes. Every new account gets free credit and a 7-day trial — no credit card required. Use it to test Web Unlocker and Browser-as-a-Service. Residential proxy is used automatically behind those products. Direct proxy URLs and dashboard credentials stay locked until you activate PAYG (minimum $5 top-up) or subscribe to a paid plan from the pricing page.
Can I use direct proxy URLs on the free trial?
No. Trial users who call /v1/proxy/fetch receive 402 with code PROXY_LOCKED. Use Web Unlocker or BaaS during the trial, or activate PAYG or a plan to unlock credentials in Dashboard → Proxies.
Billing
Am I charged for failed requests?
No. Web Unlocker is pay-for-success — failed unlocks have billing.charged: 0. BaaS is billed per active minute, and proxy fetch by bandwidth. See Pricing.
Does js_rendering cost more than fast?
No. Web Unlocker is a flat $0.0035 per successful request regardless of which lane ran.
How do I check my balance?
Every scrape response includes billing.balance_after. The usage dashboard shows full history.
How do I pay or request a refund?
Top-ups and subscriptions are completed through checkout. When Paddle is integrated, Paddle acts as Merchant of Record for those purchases. See Pricing & Billing and the Refund Policy (14-day window on eligible purchases).
Requests & results
I'm getting an empty page or just a loading skeleton.
The content is rendered by JavaScript. Use mode: "js_rendering" and add a js_wait_selector for an element that only appears once the real content loads. See JS rendering.
The site keeps blocking me (403/503/502).
Climb the anti-bot escalation ladder: force js_rendering, add a matching proxy country, wait for real content, and use a session. Failed unlocks aren't billed.
How do I extract specific fields instead of full HTML?
Add a css_selectors map — results come back in data.css_extracted. No special output format needed. See CSS extraction.
Can I submit a form or hit a JSON API?
Yes. Set method: "POST" and a body, and add custom_headers/custom_cookies as needed. See POST requests.
How do I get data from a single-page app's API?
Enable capture_xhr to capture the background fetch/XHR responses the page makes — often cleaner than parsing the DOM. See JS rendering.
Scale & performance
What's the rate limit?
There's no requests-per-second cap — only a concurrency limit per plan (5 / 10 / 25). Exceeding it returns 429 with code CONCURRENCY_LIMIT. See Rate limits.
How do I scrape thousands of URLs?
Run a worker pool sized to your concurrency limit, or use the async jobs API for large batches.
My requests are timing out.
Raise your HTTP client timeout to at least 120 seconds. js_rendering and challenge solving can take several seconds per page.
Still stuck?
Check the error reference, the status page, or reach out via the contact page.