# Surfsky

> Surfsky cloud browser for automation and scraping

- [Intro](https://docs.surfsky.io/index.md): Start a cloud browser, connect your automation code, and manage sessions with Surfsky.
- [Quickstart](https://docs.surfsky.io/quickstart.md): Configure your credentials, open a page in a cloud browser, and stop the session.
- [How it works](https://docs.surfsky.io/intro-to-surfsky.md): How Surfsky runs isolated cloud browsers, routes their traffic, builds their fingerprints, and connects them to your code.
- [Playwright](https://docs.surfsky.io/quickstart/playwright.md): Connect Playwright to a Surfsky browser over CDP, open a page, and stop the session.
- [Puppeteer](https://docs.surfsky.io/quickstart/puppeteer.md): Connect Puppeteer to a Surfsky browser, open a page, and stop the session.
- [Selenium](https://docs.surfsky.io/quickstart/selenium.md): Connect Selenium to a Surfsky browser through ChromeDriver, open a page, and stop the session.
- [Chromedp](https://docs.surfsky.io/quickstart/chromedp.md): Connect chromedp to a Surfsky browser, open a page, and stop the session.
- [Scrapy](https://docs.surfsky.io/quickstart/scrapy.md): Route Scrapy requests through a pool of Surfsky browsers.
- [Scraping API](https://docs.surfsky.io/quickstart/scraping_api.md): Use a Surfsky browser with plain HTTP requests instead of an automation framework.
- [Sessions](https://docs.surfsky.io/sessions.md): Start and stop browsers, reuse persistent profiles, and choose what browser state to save.
- [Cookies](https://docs.surfsky.io/cookies.md): Export or import a profile's cookies and troubleshoot logins that do not survive a restart.
- [Fingerprints](https://docs.surfsky.io/fingerprints.md): How Surfsky builds a profile fingerprint, what it handles automatically, and when to override it.
- [Proxies](https://docs.surfsky.io/proxies.md): Choose a Surfsky proxy pool or your own connection, target a location, and route or block domains.
- [Extensions](https://docs.surfsky.io/extensions.md): Upload a Chrome extension, load it in a browser session, and preserve its state when needed.
- [Human emulation](https://docs.surfsky.io/human_emulation.md): Surfsky's Human.* CDP commands: how the input synthesis works and the full command reference for clicks, typing, scrolling, dragging, and touch.
- [Human behavior](https://docs.surfsky.io/human-behavior.md): Choose input methods, sequence page actions, and set timing for realistic browser interactions.
- [CAPTCHA guides](https://docs.surfsky.io/category/use-cases.md): Choose a guide for the challenge on your page, with setup requirements and solver examples.
- [CAPTCHA solving](https://docs.surfsky.io/captcha-solving.md): Enable CAPTCHA solvers, choose manual or automatic mode, and check the result.
- [Datadome bypass - Automatic Captcha Solver Audio & Slider](https://docs.surfsky.io/use-cases/datadome.md): Bypass DataDome audio and slider CAPTCHAs automatically. Challenge types, proxy setup, IP-ban recovery, and manual/auto solving with code examples.
- [Turnstile](https://docs.surfsky.io/use-cases/turnstile.md): Solve a Turnstile challenge and verify that the protected page becomes available.
- [reCAPTCHA](https://docs.surfsky.io/use-cases/recaptcha.md): Configure automatic reCAPTCHA solving and verify the result on your page.
- [PerimeterX](https://docs.surfsky.io/use-cases/perimeterx.md): Handle PerimeterX press-and-hold challenges with the configured solver.
- [GeeTest](https://docs.surfsky.io/use-cases/geetest.md): Configure automatic GeeTest solving and verify the result on your page.
- [FunCaptcha](https://docs.surfsky.io/use-cases/funcaptcha.md): Use the audio solver for a FunCaptcha challenge and observe completion.
- [BLS](https://docs.surfsky.io/use-cases/bls.md): Configure automatic BLS solving and verify the result on your page.
- [Click CAPTCHA](https://docs.surfsky.io/use-cases/click.md): Click a known verification control using a CSS selector or viewport coordinates.
- [Image CAPTCHA](https://docs.surfsky.io/use-cases/image.md): Read text from a CAPTCHA image and submit the returned solution in your page.
- [Troubleshooting](https://docs.surfsky.io/troubleshooting.md): Diagnose failed starts, blocked pages, lost logins, timeouts, and CDP disconnections.
- [Debugging](https://docs.surfsky.io/debugging.md): Open DevTools for a running browser and inspect failed page loads, selectors, and network requests.
- [Screencast](https://docs.surfsky.io/screencast.md): Watch a running browser in the built-in viewer or receive image frames over WebSocket.
- [Speed optimization](https://docs.surfsky.io/speed-optimization.md): Measure browser startup, page loading, and automation time before tuning throughput.
- [Concurrency](https://docs.surfsky.io/concurrency.md): Run browser jobs in parallel, manage shared account limits, and clean up failed workers.
- [Shared cache](https://docs.surfsky.io/shared-cache.md): Reuse cached browser resources across sessions that visit the same sites.
- [Limits](https://docs.surfsky.io/limits.md): Check API rate limits, browser capacity, and proxy traffic.
- [Why Surfsky](https://docs.surfsky.io/why-surfsky.md): What Surfsky includes, when to use it, what it costs, and how it handles your data.
- [SDKs](https://docs.surfsky.io/sdk.md): Choose the Python or TypeScript client for browser automation and the Surfsky REST API.
- [Python SDK](https://docs.surfsky.io/sdk/python.md): Install the Python SDK, automate a page, run concurrent jobs, and reuse a persistent profile.
- [TypeScript SDK](https://docs.surfsky.io/sdk/typescript.md): Use the Surfsky client from Node.js or Bun to automate pages, pool browsers, and manage profiles.
- [API overview](https://docs.surfsky.io/api-reference.md): Authenticate REST requests, read response formats, and find session, profile, and browser protocol endpoints.
- [Errors](https://docs.surfsky.io/errors.md): Read API error responses, choose a retry policy, and diagnose request or browser failures.
- [Start one-time session](https://docs.surfsky.io/api-reference/profiles/start-one-time-session.md): Start a browser without a saved profile. The response returns connection fields at the top level. Use the returned internal_uuid to stop the session. Supply a proxy or VPN, or use a pool available to your account. Shared HTTP cache can be enabled separately from profile storage. See [the session gui…
- [Create profile](https://docs.surfsky.io/api-reference/profiles/create-profile.md): Create a saved profile without starting a browser. A title and fingerprint with os are required. The HTTP 201 response contains data.uuid; use it to start the profile. See [persistent profiles](/sessions#persistent-profiles).
- [List profiles](https://docs.surfsky.io/api-reference/profiles/list-profiles.md): List saved profiles. This endpoint returns a JSON array at the top level. One-time sessions are listed through active sessions instead.
- [Get profile](https://docs.surfsky.io/api-reference/profiles/get-profile.md): Read a saved profile's settings. The upstream profile service supplies the data object.
- [Update profile](https://docs.surfsky.io/api-reference/profiles/update-profile.md): Update a stopped saved profile. Omitted fields retain their values. The profile's OS identity fields cannot be changed through this request.
- [Delete profile](https://docs.surfsky.io/api-reference/profiles/delete-profile.md): Delete a stopped saved profile and its stored state. A running profile must be stopped first.
- [Delete profiles](https://docs.surfsky.io/api-reference/profiles/delete-profiles.md): Delete several saved profiles. HTTP 400 can report partial completion: inspect deleted_uuids, active_uuids, and not_found_uuids before deciding what to retry. Deleted profile state cannot be recovered through this API.
- [Start profile](https://docs.surfsky.io/api-reference/profiles/start-profile.md): Start a saved profile and restore its enabled storage types. Omitted proxy settings retain the stored proxy; explicit overrides apply to this run. Starting an already running profile can return its existing session. Use the returned connection fields as-is.
- [Stop session](https://docs.surfsky.io/api-reference/profiles/stop-session.md): Stop a running browser. Use internal_uuid from the start response; it may equal the saved profile UUID. A persistent session saves its enabled storage on a normal stop. The response may include an optional cost receipt.
- [Stop all sessions](https://docs.surfsky.io/api-reference/profiles/stop-all-sessions.md): Stop every browser on the account, including sessions used by other workers. The response separates stopped IDs from failed attempts; outer success does not mean every stop succeeded.
- [List active sessions](https://docs.surfsky.io/api-reference/profiles/list-active-sessions.md): List running browsers, including one-time and persistent sessions. Use one_time to distinguish them and internal_uuid for stop or scrape calls. Session age alone does not prove that a worker has abandoned it.
- [Scrape page](https://docs.surfsky.io/api-reference/profiles/scrape-page.md): Navigate an existing browser and return rendered HTML, cookies, and an optional PNG screenshot. Send one request or a sequential batch. Check each batch item and the target website's status. Avoid concurrent CDP work in this browser: the scraper reuses a page and closes extra pages. The gateway wait…
- [Export cookies](https://docs.surfsky.io/api-reference/profiles/export-cookies.md): Export a stopped saved profile's cookies as JSON or Netscape text. Cookies must be enabled in its storage settings. The response contains data.cookies.
- [Import cookies](https://docs.surfsky.io/api-reference/profiles/import-cookies.md): Import cookies into a stopped saved profile. Send JSON cookies serialized as a string, or Netscape text, in the cookies field. Browser storage other than cookies is not imported. See [cookies](/cookies).
- [List proxy pools](https://docs.surfsky.io/api-reference/proxies/list-proxy-pools.md): List geographic pools and their countries. The pool code selects a geographic region; proxy.tier selects shared or premium access.
- [List premium countries](https://docs.surfsky.io/api-reference/proxies/list-premium-countries.md): List premium proxy country codes and names. Use the returned code in proxy.country.
- [List premium regions](https://docs.surfsky.io/api-reference/proxies/list-premium-regions.md): List premium regions in a country. Use a returned code in proxy.region alongside proxy.country.
- [List premium cities](https://docs.surfsky.io/api-reference/proxies/list-premium-cities.md): List premium cities in a region. Set country and region together with proxy.city.
- [List premium ASNs](https://docs.surfsky.io/api-reference/proxies/list-premium-asns.md): List ASNs available for premium targeting in a country. Use a numeric ASN in proxy.asn and include proxy.country.
- [List shared countries](https://docs.surfsky.io/api-reference/proxies/list-shared-countries.md): List countries currently available in the shared proxy pool. Shared targeting supports country only.
- [Get traffic quota](https://docs.surfsky.io/api-reference/proxies/get-traffic-quota.md): Legacy alias for the premium quota endpoint. This does not combine premium and shared traffic. Read shared quota separately.
- [Get premium quota](https://docs.surfsky.io/api-reference/proxies/get-premium-quota.md): Read the remaining premium traffic allowance. Plans without an applicable quota return premium_quota_not_applicable. GB values use decimal gigabytes.
- [Get premium traffic stats](https://docs.surfsky.io/api-reference/proxies/get-premium-traffic-stats.md): Read premium traffic totals for the last 24 hours, 7 days, and 30 days. These are time windows, not per-session records.
- [Get shared quota](https://docs.surfsky.io/api-reference/proxies/get-shared-quota.md): Read shared traffic usage, remaining allowance, and reset timestamp. A value of -1 in limit and remaining fields means unlimited.
- [Get shared traffic stats](https://docs.surfsky.io/api-reference/proxies/get-shared-traffic-stats.md): Read shared traffic totals for the last 24 hours, 7 days, and 30 days.
- [List renderers](https://docs.surfsky.io/api-reference/fingerprints/list-renderers.md): Look up renderer values for a fingerprint. This response is forwarded from the fingerprint service; use the returned values instead of inventing a GPU string.
- [List screens](https://docs.surfsky.io/api-reference/fingerprints/list-screens.md): Look up screen values, optionally filtered by OS and architecture. Use the returned screen string in fingerprint.screen.
- [List device models](https://docs.surfsky.io/api-reference/fingerprints/list-device-models.md): Look up device models using the available OS, version, architecture, and device-type filters. Device models apply to Android fingerprints.
- [Upload extension](https://docs.surfsky.io/api-reference/extensions/upload-extension.md): Upload an extension ZIP using multipart file and name fields. The response returns uuid at the top level. Load it through extensions on a browser start request. Limits are 100 uploads per account and 5 extensions per browser.
- [List extensions](https://docs.surfsky.io/api-reference/extensions/list-extensions.md): List uploaded extensions. The response contains extensions and count at the top level.
- [Get extension](https://docs.surfsky.io/api-reference/extensions/get-extension.md): Read an extension's name and timestamps.
- [Update extension](https://docs.surfsky.io/api-reference/extensions/update-extension.md): Rename an extension with a JSON name field. This does not replace its archive; upload a new ZIP to update extension code.
- [Delete extension](https://docs.surfsky.io/api-reference/extensions/delete-extension.md): Delete an uploaded extension. A copy already loaded in a running browser remains until that browser stops.
- [Get solver balance](https://docs.surfsky.io/api-reference/captcha/get-solver-balance.md): Read balances for the configured CAPTCHA providers exposed by the account. An empty services list is possible. This endpoint does not validate every solver key; see [CAPTCHA configuration](/captcha-solving).

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)