AdsCrawl Setup: From API Key to First Browser Request

AdsCrawl turns real browser actions into a unified API. Instead of managing headless Chrome, proxies, and retry logic yourself, you send a request and receive a screenshot, extracted HTML, Markdown, or a live Chrome DevTools Protocol (CDP) session. This guide walks through the complete setup path: creating an account, generating an API key, making your first authenticated request, configuring browser behavior, and moving into production with remote CDP control.

The setup process is intentionally short. You can go from signup to a working screenshot request in under ten minutes if you follow the request format closely.

What You Need Before Starting

AdsCrawl is an HTTP API, so the requirements are minimal:

• An AdsCrawl account with an active API key
• A tool that can send HTTP requests: cURL, Postman, Node.js, or Python
• A reachable HTTP(S) URL to test against
• Basic familiarity with JSON request bodies

No browser installation, WebDriver binary, or local Chrome instance is required. The platform manages browser sessions, proxies, and User-Agent rotation server-side.

Step 1: Create Your Account and API Key

AdsCrawl Setup: From API Key to First Browser Request - Step 1: Create Your Account and API Key.

The first setup task is account creation. After signing up, open the dashboard and navigate to the key management section. The dashboard is also where you track credit usage, review failed tasks, and debug request payloads.

Create a full API key and store it somewhere secure. The key is sent as the x-api-key header on every request. Treat it like a password: do not commit it to public repositories, and rotate it if it leaks.

If you already have an account but cannot access the dashboard, the AdsCrawl Login guide covers sign-in steps, key management, and common authentication troubleshooting.

Step 2: Understand the Request Contract

Every browser task uses the same envelope:

• Method: POST
• Base URL: https://api.adscrawl.net
• Headers: x-api-key and content-type: application/json
• Body: JSON with a required url field plus optional browser configuration

The x-api-key header must be present on every call. Missing or invalid keys return 401. The body must be valid JSON; malformed payloads return 400.

Required and Common Fields

Field	Required	Purpose
url	Yes	Target HTTP(S) URL using port 80 or 443
viewport	No	Browser viewport width and height for screenshots
fullPage	No	Capture the full page height; defaults to true
selector	No	Capture only the first matching element
waitUntil	No	Navigation wait strategy: load, domcontentloaded, or networkidle
timeoutMs	No	Positive timeout up to 3,600,000 ms
countryCode	No	Managed proxy region or GLOBAL for dynamic exit
userAgentMode	No	custom or random User-Agent selection
cookies	No	Cookie list injected before navigation
fingerprint	No	Browser fingerprint settings

Choosing the Right waitUntil Value

waitUntil controls when the browser considers navigation complete:

• domcontentloaded waits for HTML parsing without secondary resources. Use this for fast HTML extraction when images and stylesheets are not needed.
• load waits for the window load event, including dependent resources. This is the default and a good general-purpose choice.
• networkidle waits until no network connections exist for at least 500 ms. Use it for JavaScript-heavy pages, but be aware that long polling, analytics, or lazy-loaded content can cause timeouts.

Step 3: Make Your First Screenshot Request

Start with a simple cURL call to verify authentication and connectivity:

curl -sS -X POST "https://api.adscrawl.net/screenshot" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "viewport": {"width": 1440, "height": 900},
    "fullPage": true,
    "waitUntil": "load",
    "countryCode": "GLOBAL",
    "userAgentMode": "random",
    "userAgentOs": "windows"
  }' \
  --output page.png

A successful response returns a 200 status with a Content-Type: image/png header and a binary PNG stream. Open page.png to confirm the capture worked.

Common First-Request Errors

Status	Meaning	Fix
400	Invalid JSON, URL, cookies, proxy, region, or User-Agent parameters	Validate your JSON and field values
401	Missing or invalid x-api-key	Check the header name and key value
402	Insufficient balance	Add credits or check your plan
422	Selector did not match or task payload rejected	Verify the selector exists on the page
429	Rate limited	Slow down request frequency
502	Proxy unreachable or target HTTP failure	Retry with a different region or URL
504	Task, navigation, or proxy timeout	Increase timeoutMs or simplify waitUntil

Step 4: Extract HTML and Markdown

Screenshot capture is only one endpoint. For data extraction, use the HTML endpoint with waitUntil: "domcontentloaded" when you need parsed content quickly:

curl -sS -X POST "https://api.adscrawl.net/html" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "waitUntil": "domcontentloaded"
  }'

For single-page applications that render content client-side, switch to networkidle and add a generous timeoutMs. If you need only a specific section, pass a selector to capture the first matching element instead of the entire document.

Step 5: Configure Proxies, Locale, and Fingerprints

Production scraping often requires regional exit points and consistent browser identity. AdsCrawl supports several configuration layers:

• countryCode: Use a two-letter region code to prefer a trusted proxy in that region, or GLOBAL for a dynamic exit from 15 popular regions. Omit the field for a random trusted proxy.
• locale and timezoneId: Set browser locale such as en-US and an IANA timezone such as Asia/Shanghai to match target-site expectations.
• geolocation: Provide latitude and longitude coordinates when a site checks location.
• fingerprint: When omitted, every signal defaults to random while keeping OS, GPU, CPU, memory, fonts, and device signals coherent. This reduces obvious automation fingerprints.
• cookies: Inject a cookie list before navigation to maintain session state across requests.

Custom proxies are also supported through the proxy field, but they cannot be combined with countryCode.

Step 6: Move to Remote CDP for Interactive Control

Screenshot and HTML endpoints are synchronous metered requests. For interactive workflows, remote CDP gives you direct control over a live browser session:

1. Use your x-api-key to create a CDP session.
2. The response includes a cdpBaseUrl with an embedded data token that protects discovery and CDP WebSockets.
3. Live control uses a single-use controlToken valid for 30 seconds.
4. Connect your preferred CDP client to the WebSocket endpoint and drive the browser directly.

This is useful for AI agents that need to click, type, scroll, and observe page state in real time. The session management endpoints also support listing and deleting active sessions.

Step 7: Integrate with Python or Node.js

Most teams move beyond cURL quickly. The same request contract works from any HTTP client.

Python Example

import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://api.adscrawl.net/screenshot",
    headers={
        "content-type": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "url": "https://example.com",
        "viewport": {"width": 1440, "height": 900},
        "fullPage": True,
        "waitUntil": "load",
    },
)

if response.status_code == 200:
    with open("page.png", "wb") as f:
        f.write(response.content)
else:
    print(response.status_code, response.text)

Node.js Example

const response = await fetch("https://api.adscrawl.net/html", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.ADSCRAWL_API_KEY,
  },
  body: JSON.stringify({
    url: "https://example.com",
    waitUntil: "domcontentloaded",
  }),
});

const html = await response.text();
console.log(html);

For a broader comparison of how AdsCrawl fits alongside other browser automation approaches, see the AdsCrawl vs axiom.ai vs Playwright comparison.

Step 8: Validate Your Setup in Production

Before scaling up, run a short validation checklist:

1. Authentication works: Your key returns 200 on a known-good URL.
2. Error handling is in place: Your code handles 401, 402, 429, and 5xx responses with retries or alerts.
3. Timeout strategy is deliberate: You chose waitUntil values based on page type, not defaults alone.
4. Credits are monitored: The dashboard shows usage and remaining balance.
5. Secrets are protected: API keys live in environment variables or a secrets manager.

AdsCrawl Setup vs. Self-Hosted Browser Automation

If you are deciding between AdsCrawl and running your own browser fleet, the setup trade-offs are clear:

Factor	AdsCrawl	Self-hosted Playwright/Selenium
Initial setup time	Minutes	Hours to days
Infrastructure maintenance	None	Proxy rotation, browser updates, retry logic
Concurrency	Managed, credit-based	Your own hardware limits
Interactive control	Remote CDP sessions	Local browser instances
Cost model	Freemium credits	Infrastructure plus engineering time

AdsCrawl makes sense when you want browser capabilities behind an API without owning the infrastructure. Self-hosted frameworks offer more control but require ongoing maintenance. For a deeper look at when each approach wins, the Selenium review covers the self-hosted framework perspective.

Related reading

• AdsCrawl Download: Browser Automation API Setup Guide - Learn how to download, install, and start using AdsCrawl for browser automation, HTML extraction, screenshots, and CDP control. Setup guide with code examples.
• AdsCrawl Review: Browser Automation API Tested for AI Agents - Hands-on AdsCrawl review covering the browser automation API, screenshots, HTML extraction, CDP control, pricing, and real-world performance for AI agents.

Sources and further reading

• Notes on browser automation, collection engineering, and AI workflows - The blog shares product practice, technical breakdowns, and field notes for teams building data workflows with real browsers.
• ‎Alarm Clock - Wake up Music App - Time to Plan your 24/7 Routine

Frequently Asked Questions

How do I get my AdsCrawl API key?

Sign up for an account, open the dashboard, and create a full API key in the key management section. Use that key as the x-api-key header on every request.

What is the base URL for AdsCrawl API requests?

The base URL is https://api.adscrawl.net. Endpoints such as /screenshot and /html are appended to this base.

What does the 402 INSUFFICIENT_CREDITS error mean?

Your account balance does not cover the requested task. The response includes your current balance and the required credits. Add credits or upgrade your plan to continue.

Can I combine a custom proxy with countryCode?

No. The proxy field and countryCode field are mutually exclusive. Choose one routing method per request.

How long is the CDP control token valid?

The single-use controlToken for live CDP control is valid for 30 seconds. Create a new session or token if it expires.

What is the maximum request body size?

Request bodies are limited to 1 MiB. Larger payloads are rejected as invalid JSON with a 400 response.

Conclusion

AdsCrawl setup follows a simple pattern: create an API key, send a JSON request with a target URL and browser options, and handle the response. The main decisions are choosing the right waitUntil strategy, configuring proxy and fingerprint settings for your target sites, and deciding when to move from synchronous extraction to interactive CDP sessions.

Start with a single screenshot request to validate authentication. Then add HTML extraction, regional routing, and error handling as your workflow matures. For more detailed endpoint documentation and field notes on browser automation, refer to the AdsCrawl documentation and the AdsCrawl blog.