Crawleo Documentation

Headful Browser API

curl --request GET \
  --url https://api.crawleo.dev/headful-browser \
  --header 'x-api-key: <x-api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://api.crawleo.dev/headful-browser', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
}

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>'

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://api.crawleo.dev/headful-browser', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
}

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

Sites with Bot Protection

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.

JavaScript-Heavy SPAs

For single-page applications that require full browser rendering including deferred JavaScript execution, not just basic JS rendering.

Screenshot Capture

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

string

required

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

Required Parameters

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

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.

string

default:"markdown"

Output format for the crawled page content.

Value	Description	Best For
`markdown`	Structured markdown (default)	LLMs, RAG pipelines
`enhanced_html`	Clean HTML without ads/scripts	Processing pipelines
`raw_html`	Complete original HTML source	Full content preservation
`page_text`	Plain extracted text	Simple text extraction

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"

import requests

response = requests.get(
    "https://api.crawleo.dev/headful-browser",
    params={
        "urls": "https://example.com",
        "output_format": "markdown"
    },
    headers={
        "x-api-key": "YOUR_API_KEY"
    }
)
data = response.json()
print(data)

const response = await fetch(
  "https://api.crawleo.dev/headful-browser?urls=https://example.com&output_format=markdown",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY"
    }
  }
);
const data = await response.json();
console.log(data);

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
}

string

"success" on a successful response.

array

Array of result objects, one per URL.

Show Result object properties

string

The crawled URL.

string

Markdown content (if output_format=markdown).

string

Raw HTML source (if output_format=raw_html).

string

Cleaned HTML (if output_format=enhanced_html).

string

Plain text content (if output_format=page_text).

string

URL to the captured screenshot image (if screenshot=true).

boolean

Whether the crawl was ultimately blocked. Failed/blocked requests cost 0 credits.

integer

Number of credits consumed by this request (50 per successful URL).

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 Status	Meaning
`200`	Success — content returned
`400`	Invalid parameters (missing `urls`, invalid format)
`401`	Invalid or missing API key
`429`	Credits exhausted or concurrent request limit reached
`500`	Headful 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

Getting Started

API Overview

Search APIs

Crawling APIs

Core Concepts

MCP Integration

Integrations

Headful Browser API

Overview

When to Use Headful Browser

Endpoint

Parameters

Required Headers

Required Parameters

Optional Parameters

Example Requests

Basic Usage

With Screenshot & Geo-Routing

Response

MCP Usage

MCP Integration

Error Handling

​Overview

​When to Use Headful Browser

​Endpoint

​Parameters

​Required Headers

​Required Parameters

​Optional Parameters

​Example Requests

​Basic Usage

​With Screenshot & Geo-Routing

​Response

​MCP Usage

MCP Integration

​Error Handling

Overview

When to Use Headful Browser

Endpoint

Parameters

Required Headers

Required Parameters

Optional Parameters

Example Requests

Basic Usage

With Screenshot & Geo-Routing

Response

MCP Usage

Error Handling