# AdsCrawl Frequently Asked Questions

> Practical answers about AdsCrawl's browser APIs, temporary CDP sessions and saved Cloud Browser environments.

The [official documentation](https://docs.adscrawl.net/api-reference/introduction) is the authoritative reference for API contracts and current limits. This FAQ summarizes common questions; consult the linked endpoint documentation before integrating. The [OpenAPI specification](https://www.adscrawl.net/openapi.yaml) describes the public HTTP API.

## 1. How do I get started and authenticate?

Create an account, copy your API key from the dashboard and send it in the `x-api-key` header to `https://api.adscrawl.net`. Keep the key on your server. A dashboard login session is not an API key. The free request generator creates examples with placeholders; it does not collect your key or execute requests.

References: [Quickstart](https://docs.adscrawl.net/quickstart), [API introduction](https://docs.adscrawl.net/api-reference/introduction), [API request generator](https://www.adscrawl.net/tools/api-request-builder/).

## 2. Which API should I choose for a JavaScript-rendered page?

Use `POST /html` for rendered content, `POST /spa-extract` for structured fields and `POST /screenshot` for a PNG. These browser tasks render the page before returning their output. Where the endpoint supports it, use a wait condition or selector for asynchronously loaded content. Choose Remote CDP for scripted interactions and Cloud Browser for reusable profiles with a live viewer.

References: [Browser tasks](https://docs.adscrawl.net/concepts/browser-tasks), [Remote CDP](https://docs.adscrawl.net/concepts/remote-cdp), [Cloud Browser](https://docs.adscrawl.net/concepts/cloud-browsers).

## 3. Can I get Markdown instead of HTML?

Yes. Set `contentMode` to `markdown` on `POST /html`. Use `html` for rendered markup or `json` for structured article content. Markdown and article JSON use Readability extraction; they are intended for readable article content and can return `READABILITY_CONTENT_NOT_FOUND` when no suitable article is found. Article JSON is not arbitrary schema extraction.

References: [HTML API](https://docs.adscrawl.net/api-reference/html), [Web to Markdown API](https://www.adscrawl.net/web-to-markdown-api/).

## 4. How do I extract specific fields?

Call `POST /spa-extract` with `mode: "extract"` and define the fields you need. DOM fields use CSS selectors; network fields read matching responses. Published templates are another option. Check `missingFields` to see which values were not found. The legacy `schema` mapping is not a JSON Schema response validator.

References: [Structured extraction API](https://docs.adscrawl.net/api-reference/spa-extract), [Web scraping API](https://www.adscrawl.net/web-scraping-api/).

## 5. Can I capture a full page or one element?

Yes. `POST /screenshot` returns PNG bytes. Set `fullPage` for the full page, or supply a CSS `selector` to capture its first matching element. When both are supplied, `selector` takes precedence. Save the response as a binary file; an unmatched selector returns an error rather than a full-page fallback.

References: [Screenshot API reference](https://docs.adscrawl.net/api-reference/screenshot), [Screenshot product page](https://www.adscrawl.net/screenshot-api/).

## 6. Can I use Node.js, Python, Playwright or Puppeteer?

The HTTP APIs work with JavaScript `fetch`, Python `requests`, cURL and other HTTP clients. For browser automation, create a Remote CDP session and pass its returned `cdpBaseUrl` to Playwright `connectOverCDP`, or use the documented discovery flow for Puppeteer. Keep the scoped token in the connection URL. Release the temporary session when finished.

References: [CDP session API](https://docs.adscrawl.net/api-reference/cdp-sessions), [Playwright automation guide](https://docs.adscrawl.net/guides/playwright-automation).

## 7. What makes Cloud Browser different from temporary CDP?

Cloud Browser saves reusable browser profiles and provides a live viewer while a runtime is running. It runs AdsPower fingerprint browsers with real native fingerprints, isolated environments and browser updates that follow AdsPower. Each profile separates fingerprint settings and browser state. These AdsPower advantages apply to Cloud Browser; temporary Remote CDP is a separate, time-limited session workflow. A saved Cloud Browser profile does not by itself guarantee a CDP endpoint.

References: [Cloud Browser concepts](https://docs.adscrawl.net/concepts/cloud-browsers), [Cloud Browser API product page](https://www.adscrawl.net/cloud-browser-api/), [Remote CDP concepts](https://docs.adscrawl.net/concepts/remote-cdp).

## 8. Can I use my own proxy, and does Cloud Browser require a paid plan?

Supported browser tasks and CDP sessions accept custom proxy settings. Starting Cloud Browser runtime requires a paid plan. Every Cloud Browser launch requires an explicit custom proxy; API-key starts of existing profiles also require an explicit valid top-level proxy, even if a proxy was saved earlier. Put credentials in their designated fields, not in the proxy server URL. Check each endpoint's proxy schema.

References: [Cloud Browser launch API](https://docs.adscrawl.net/api-reference/cloud-browsers-launch), [API schemas](https://docs.adscrawl.net/api-reference/schemas), [Pricing](https://www.adscrawl.net/pricing/).

## 9. Can I use cookies to access signed-in pages?

Supported tasks and Cloud Browser workflows accept cookies. Use cookies for accounts you are authorized to access, and check their domain, path and expiration. For a multi-step sign-in flow, use browser automation through Remote CDP. Saved browser state helps reuse a Cloud Browser profile, but a site's session expiry or authentication requirements still apply.

References: [API schemas](https://docs.adscrawl.net/api-reference/schemas), [Cloud Browser session guide](https://docs.adscrawl.net/guides/cloud-browser-sessions), [Authenticated web scraping](https://www.adscrawl.net/authenticated-web-scraping/).

## 10. Will closing the viewer stop a Cloud Browser?

No. Closing the viewer leaves the runtime running and usage charges continue. Call the stop endpoint and confirm `runtime.status` is `stopped`. Stopping preserves the profile and snapshots for reuse. Viewer access requires the owner's login session; possession of an API key alone does not grant viewer access. For a temporary Remote CDP session, release it with `DELETE /cdp/sessions/{sessionId}`.

References: [Cloud Browser session guide](https://docs.adscrawl.net/guides/cloud-browser-sessions), [Cloud Browser concepts](https://docs.adscrawl.net/concepts/cloud-browsers), [CDP session API](https://docs.adscrawl.net/api-reference/cdp-sessions).

## 11. What should I do about timeouts, credits or rate limits?

For timeouts, inspect the error response, check the target URL and proxy, and verify that the waited-for selector can appear. Adjust waits and timeouts only within the endpoint's documented limits. For HTTP `402`, check your credits and plan in the dashboard. For HTTP `429`, lower concurrency and retry with backoff. Current plan limits are listed on the pricing page and in your account.

References: [API introduction](https://docs.adscrawl.net/api-reference/introduction), [API schemas](https://docs.adscrawl.net/api-reference/schemas), [Pricing](https://www.adscrawl.net/pricing/).

## 12. Can my coding agent help me integrate AdsCrawl?

Yes. The homepage includes a setup prompt for coding agents. Follow the account setup and API-key approval flow in your browser, and keep the resulting key in your server environment. Give the agent the documentation index and OpenAPI specification to select the correct endpoint and request schema. The request generator can also provide starter cURL, JavaScript or Python examples without sending a network request.

References: [Homepage setup prompt](https://www.adscrawl.net/), [Documentation index](https://www.adscrawl.net/docs/llms.txt), [OpenAPI specification](https://www.adscrawl.net/openapi.yaml), [API request generator](https://www.adscrawl.net/tools/api-request-builder/).