Skip to main content
GET
https://api.crawleo.dev
/
headful-browser
Headful Browser API
curl --request GET \
  --url https://api.crawleo.dev/headful-browser \
  --header 'x-api-key: <x-api-key>'
{
  "status": "<string>",
  "data": [
    {
      "url": "<string>",
      "markdown": "<string>",
      "raw_html": "<string>",
      "enhanced_html": "<string>",
      "page_text": "<string>",
      "screenshot": "<string>",
      "blocked": true
    }
  ],
  "credits_used": 123,
  "credits_remaining": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.crawleo.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Headful Browser API provides high-fidelity crawling using a real headed browser running on dedicated GPU hardware with SOAX residential proxies. It uses advanced human-like behavior simulation to bypass bot-detection systems including Cloudflare, Akamai, DataDome, and PerimeterX.
Cost: 50 credits per URL. Always try the Crawler API first — use the Headful Browser API only when standard crawling is blocked. Failed requests cost 0 credits.

​
When to Use Headful Browser

Use when a site is protected by Cloudflare, Akamai, DataDome, PerimeterX, or similar bot-detection systems that return CAPTCHA or empty responses to standard crawlers.
For single-page applications that require full browser rendering including deferred JavaScript execution, not just basic JS rendering.
Sites with aggressive fingerprinting (e.g., Amazon, LinkedIn, Instagram) that require a realistic browser fingerprint to return content.
Any time you need a visual screenshot of a page for verification or monitoring purposes.

​
Endpoint

GET https://api.crawleo.dev/headful-browser
Cost: 50 credits per URL

​
Parameters

​
Required Headers

​
x-api-key
string
required
Your Crawleo API key for authentication. Alternatively, use Authorization: Bearer YOUR_API_KEY.Example: x-api-key: YOUR_API_KEY

​
Required Parameters

​
urls
string
required
One or more URLs to crawl. Accepts a single URL or a comma-separated list.Examples:
  • urls=https://example.com
  • urls=https://example.com,https://example.org

​
Optional Parameters

​
country
string
default:"us"
ISO 3166-1 alpha-2 country code for residential proxy geolocation. Routes requests through a proxy server in the specified country.Supported values: us, gb, de, fr, jp, in, br, ca, au, and more.
​
output_format
string
default:"markdown"
Output format for the crawled page content.
ValueDescriptionBest For
markdownStructured markdown (default)LLMs, RAG pipelines
enhanced_htmlClean HTML without ads/scriptsProcessing pipelines
raw_htmlComplete original HTML sourceFull content preservation
page_textPlain extracted textSimple text extraction
​
screenshot
boolean
default:"false"
Set to true to capture a full-page screenshot of the rendered page. Screenshot is returned as a URL.

​
Example Requests

​
Basic Usage

curl -X GET "https://api.crawleo.dev/headful-browser?urls=https://example.com&output_format=markdown" \
  -H "x-api-key: YOUR_API_KEY"

​
With Screenshot & Geo-Routing

cURL
curl -X GET "https://api.crawleo.dev/headful-browser?urls=https://example.com&output_format=markdown&screenshot=true&country=gb" \
  -H "x-api-key: YOUR_API_KEY"

​
Response

A successful response returns an array of results for each URL: 
{
  "status": "success",
  "data": [
    {
      "url": "https://example.com",
      "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...",
      "raw_html": "<!DOCTYPE html>...",
      "enhanced_html": "<html>...",
      "page_text": "Example Domain\nThis domain is for use...",
      "screenshot": "https://storage.crawleo.dev/screenshots/abc123.png",
      "blocked": false
    }
  ],
  "credits_used": 50,
  "credits_remaining": 49950
}
​
status
string
"success" on a successful response.
​
data
array
Array of result objects, one per URL.
​
credits_used
integer
Number of credits consumed by this request (50 per successful URL).
​
credits_remaining
integer
Credits remaining in your monthly allowance after this request.

​
MCP Usage

The headful_browser tool is available when using Crawleo via MCP. AI assistants automatically use it when standard crawling fails: 
headful_browser(url="https://protected-site.com", output_format="markdown", country="us")
The MCP tool accepts a single URL (not a comma-separated list). For multiple pages, call the tool once per URL.

MCP Integration

Connect AI assistants like Claude, Cursor, and GitHub Copilot to Crawleo via MCP.

​
Error Handling

HTTP StatusMeaning
200Success — content returned
400Invalid parameters (missing urls, invalid format)
401Invalid or missing API key
429Credits exhausted or concurrent request limit reached
500Headful browser service unavailable
If the headful browser service is temporarily unavailable, you will receive a 500 response. No credits are charged for failed requests.
Last modified on April 16, 2026