API Reference

UnblockingAPI fetches public URLs and returns clean HTML — with optional JavaScript rendering, geo-routing and smart wait strategies for dynamic pages.

Base URL
https://api.unblockingapi.com

Want to test requests directly in your browser? Open the interactive Swagger UI to explore endpoints and try them live with your API key.

Quick start

Grab your API key and make your first request:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.unblockingapi.com/unblock?url=https://example.com"

Prefer hands-on help?

Our developers can help integrate UnblockingAPI into your existing application or scraper.

Get setup help

Authentication

Every request needs your API key, sent any one of these ways:

X-Api-Key: <key>headerrecommended
Authorization: Bearer <key>header
?key=<key>query parameterhandy for quick browser tests
# Header (recommended)
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.unblockingapi.com/unblock?url=https://example.com"

# Bearer token
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.unblockingapi.com/unblock?url=https://example.com"

# Query parameter
curl "https://api.unblockingapi.com/unblock?url=https://example.com&key=YOUR_API_KEY"

Rate limits

Rate limits depend on your plan and are enforced per API key.

Each plan includes:

  • a concurrent request limit
  • an hourly throughput limit
  • fair use and abuse prevention controls

Exceeding your plan limits returns 429. See Pricing for current plan limits.

Some plans may also include short-window burst limits to protect reliability.

/unblock

Fetch a public URL and get clean HTML back. Both GET and POST are supported — POST takes a JSON body with the same fields.

GETPOST/unblock
# GET request
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.unblockingapi.com/unblock?url=https://example.com&location=se"

# POST request
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "render": true, "location": "se"}' \
  "https://api.unblockingapi.com/unblock"

Parameters

urlstringrequired

URL to fetch. Must be http(s) and not point at a media/binary file.

renderbooleandefault: false

Render with a real browser (executes JavaScript). Required for wait and block_assets. Slower than a plain fetch — try without it first, and only enable it if the response is missing content.

locationstring

2-letter country code for geo-routing where supported. Examples: se, us, gb, de.

waitstring

Wait grammar (requires render=true). See Wait grammar below.

block_assetsbooleandefault: true

Skip CSS, JS, images & fonts for a faster render. Defaults to true when render=true; pass false to load all assets. Requires render=true.

remove_scriptsbooleandefault: false

Strip all <script> tags from the returned HTML.

remove_stylesheetsbooleandefault: false

Strip all <style> tags from the returned HTML.

remove_svgsbooleandefault: false

Strip all <svg> tags from the returned HTML.

Response format

Every response follows the same envelope:

{
  "job_id": "abc123",
  "url": "https://example.com",
  "status": "succeeded",
  "http_response_code": 200,
  "response_time_ms": 1250,
  "render": false,
  "location": "se",
  "response_format": "html",
  "response": "<!doctype html>..."
}
job_idstring

Unique ID for this request.

urlstring

The URL that was fetched.

status"succeeded" | "failed"

"succeeded" for 2xx and 404 targets; "failed" otherwise.

http_response_codeinteger

The target's actual HTTP status code. On a 500 response, this holds the real upstream code (e.g. 403, 429).

response_time_msinteger

Time taken in milliseconds.

renderboolean

Whether browser rendering was used.

locationstring | null

Country code used, or null.

response_format"html" | "json"

"html" for /unblock, "json" for template endpoints.

responsestring | object

HTML string or structured JSON (templates).

errorstring

Present only when status is "failed".

Wait grammar

The wait parameter accepts a comma-separated list of up to 5 steps. Requires render=true.

Load eventstring

Optional first step. One of: domcontentloaded, load, networkidle, networkidle2.

CSS selectorstring

Wait for an element matching this selector to appear. Example: .results, h3.

networkidle:<ms>string

Wait until network is idle for the given ms (100–5000).

domstable:<ms>string

Wait until DOM is stable for the given ms (100–5000).

Examples

# Wait for h3 after DOMContentLoaded
?wait=domcontentloaded,h3

# Wait for results div, then network idle for 500ms
?wait=.results,networkidle:500

# Full page load, then wait for DOM stability
?wait=load,domstable:1000

Error codes

200

Success — the target returned a 2xx. Body carries the fetched content.

401

Missing or invalid API key.

404

Target returned 404. Treated as a successful result (status is "succeeded"), not a failure.

422

Invalid parameters — check the error message for details.

429

Rate limit exceeded. Back off and retry.

500

Request failed due to an upstream error, block, captcha challenge or render failure. Check http_response_code and error for details.

503

Service temporarily unavailable — proxy pool exhausted or render backend saturated. Retry shortly.

504

Timed out waiting for the target or render backend.

Working on a tricky target? Talk to us — we can help tune routing, rendering and request strategy for your use case.

Templates

Templates are optional structured endpoints for supported public pages. They return parsed JSON instead of raw HTML. Same authentication and rate limits apply.

Availability may vary by target, region, rendering mode and anti-bot behavior. Template access may require approval or a custom plan.

How templates work

Each template has its own endpoint under /api/. You pass a public URL (and optional parameters), and the response comes back as structured JSON.

Example template types

Property listing template

Structured data from a property listing page — price, size, rooms, features and more.

Search results template

Structured search results — titles, snippets, URLs and pagination.

Template endpoints are optional structured endpoints for supported public pages. Use must comply with the Acceptable Use Policy. For available templates and access, contact us.

Ready to start?

Get your API key and make your first request in seconds.

Get API key