API решения капчи Прокси API Fingerprint API Browser API Scraper API

Scraper API — руководство для пользователей API

Это руководство описывает работу с Scraper API напрямую по HTTP: создание задач, синхронное выполнение, получение результатов, просмотр истории, загрузку веб-страниц и поиск Google.

Quick Start — получить HTML страницы

Самый простой сценарий — синхронно загрузить страницу и получить её HTML в JSON.

Понадобятся:

адрес API;
API-ключ;
URL страницы.

Задайте адрес API и ключ:

bash Copy

BASE_URL="https://scraper.2captcha.com"
API_KEY="<ВАШ_API_КЛЮЧ>"

Отправьте запрос:

bash Copy

curl -i -X POST "$BASE_URL/tasks/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "scrape",
    "url": "https://example.com",
    "data_format": "raw",
    "format": "json"
  }'

Параметры задачи:

Поле	Значение	Назначение
`task_type`	`scrape`	загрузить веб-страницу
`url`	`https://example.com`	адрес целевой страницы
`data_format`	`raw`	вернуть исходный HTML
`format`	`json`	поместить результат в JSON

Успешный ответ имеет HTTP-статус 200 и примерно такое тело:

json Copy

{
  "status": 200,
  "headers": {
    "content-type": "text/html; charset=utf-8"
  },
  "body": "<!doctype html><html>...</html>"
}

Здесь:

status — HTTP-статус целевой страницы;
headers — заголовки ответа целевой страницы;
body — полученный HTML.

Метаданные задачи находятся не в теле, а в ответном заголовке x-debug:

http Copy

x-debug: {"response_id":"...","add_datetime":1747983214000,"finish_datetime":1747983220000,"price":0.0005,"status_code":200,"status_message":"OK"}

Проверьте:

внешний HTTP-статус Scraper API равен 200;
status в JSON равен ожидаемому статусу целевой страницы;
body не пуст и содержит нужный HTML;
x-debug.response_id заполнен;
x-debug.status_code совпадает с внешним HTTP-статусом;
x-debug.price содержит фактическую стоимость задачи.

Если нужен только HTML без JSON:

bash Copy

curl -X POST "$BASE_URL/tasks/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "scrape",
    "url": "https://example.com",
    "data_format": "raw",
    "format": "raw"
  }' \
  --output page.html

Результат будет сохранён в page.html.

1. Адрес API

Production:

text Copy

https://scraper.2captcha.com

bash Copy

BASE_URL="https://scraper.2captcha.com"

2. Авторизация

API поддерживает два способа авторизации. Для одного запроса достаточно одного способа.

2.1. API-ключ

Рекомендуемый способ:

http Copy

Authorization: Bearer <API_KEY>

Пример:

bash Copy

curl -X POST "$BASE_URL/tasks/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "scrape",
    "url": "https://example.com"
  }'

Не передавайте API-ключ в URL, не сохраняйте его в репозитории и не прикладывайте к логам или баг-репортам.

2.2. Email и пароль

Для POST-запросов email и password передаются в JSON-теле:

json Copy

{
  "email": "user@example.com",
  "password": "secret"
}

Для GET-запросов они передаются в query string:

text Copy

GET /task_history?email=user@example.com&password=secret

Этот способ менее безопасен для GET-запросов: URL может попасть в историю клиента, журналы прокси и серверные логи. По возможности используйте API-ключ.

2.3. Требования по эндпоинтам

Эндпоинт	Авторизация
`POST /tasks/request`	обязательна
`POST /tasks/sync`	обязательна
`GET /task_history`	обязательна
`GET /tasks/result/:response_id`	не требуется

При неверных или отсутствующих учётных данных API возвращает:

http Copy

401 Unauthorized

3. Общие правила запросов

Для POST-запросов используйте Content-Type: application/json.
Параметры метода передаются плоско в JSON-теле, без вложенного объекта params.
task_type можно передать в теле или в query string. Если он указан в обоих местах, приоритет имеет тело.
Размер JSON-тела не должен превышать 10 000 байт.
Поля email и password используются только для авторизации и не сохраняются в задании.
Фактическая стоимость зависит от метода, тарифа и окружения. Проверяйте поле price в заголовке x-debug.

Правильно:

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "data_format": "raw"
}

Не используйте вложенный params, если отдельная версия API явно не требует обратного:

json Copy

{
  "task_type": "scrape",
  "params": {
    "url": "https://example.com"
  }
}

4. Заголовок `x-debug`

Все ответы API содержат заголовок x-debug. В нём находятся метаданные задачи и самого ответа API:

http Copy

x-debug: {"response_id":"0193f2a4-1b2c-7d3e-8f4a-5b6c7d8e9f0a","add_datetime":1747983214000,"finish_datetime":1747983220000,"price":0.0005,"status_code":200,"status_message":"OK"}

Поле	Тип	Описание
`response_id`	string или `null`	идентификатор задачи; `null`, если задача не создана
`add_datetime`	number или `null`	время создания задачи, Unix milliseconds
`finish_datetime`	number или `null`	время завершения; `null`, пока задача выполняется
`price`	number	фактическая стоимость выполнения
`status_code`	number	HTTP-статус Scraper API
`status_message`	string	текст HTTP-статуса

HTTP-статус API и статус целевой страницы — разные значения:

text Copy

HTTP 200 от Scraper API
└── status: 404 внутри результата — целевой сайт ответил 404

5. Синхронное выполнение: `POST /tasks/sync`

Эндпоинт создаёт задачу и ожидает её завершения в рамках одного HTTP-запроса.

5.1. Общие параметры

Поле	Тип	Обязательно	По умолчанию	Описание
`task_type`	string	да	—	метод: `scrape` или `google_search`
`format`	`json` или `raw`	нет	`json`	формат результата метода
`timeout`	number	нет	`60`	время ожидания в секундах, допустимо `1–120`
`email`	string	при авторизации паролем	—	email пользователя
`password`	string	при авторизации паролем	—	пароль пользователя
`coordinates`	object	нет	—	`{ "lat": number, "lon": number, "radius"?: number }`
`uule`	string	нет	—	Canonical Name или `lat,lon[,radius]`
`cdpurl`	string	нет	—	WebSocket URL собственного Chrome/CDP
остальные поля	зависит от метода	зависит от метода	—	параметры `scrape` или `google_search`

5.2. Успешный ответ

При успешном выполнении API возвращает:

HTTP 200;
результат задачи в теле;
метаданные задачи в x-debug.

Для scrape с format: "json" фактически используется такая структура:

json Copy

{
  "status": 200,
  "headers": {
    "content-type": "text/html; charset=utf-8"
  },
  "body": "<!DOCTYPE html>..."
}

Для format: "raw" возвращается непосредственно содержимое body: HTML, Markdown или бинарный PNG.

5.3. Таймаут

Если задача не завершилась за указанное время:

http Copy

408 Request Timeout

При format: "json":

json Copy

{
  "error": "timeout",
  "response_id": "0193f2a4-1b2c-7d3e-8f4a-5b6c7d8e9f0a"
}

Задача продолжает выполняться. Используйте полученный response_id для последующего запроса /tasks/result/:response_id.

5.4. Ошибка выполнения

Если задача завершилась с ошибкой:

http Copy

422 Unprocessable Entity

Пример:

json Copy

{
  "error": "max_restarts_exceeded"
}

6. Асинхронное выполнение

Асинхронный сценарий состоит из двух шагов:

создать задачу через POST /tasks/request;
получить результат через GET /tasks/result/:response_id.

6.1. Создание задачи: `POST /tasks/request`

Пример:

bash Copy

curl -X POST "$BASE_URL/tasks/request" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "scrape",
    "url": "https://example.com",
    "data_format": "raw",
    "format": "json"
  }'

Успешный ответ:

http Copy

201 Created

json Copy

{
  "response_id": "0193f2a4-1b2c-7d3e-8f4a-5b6c7d8e9f0a"
}

При format: "raw" тело содержит только ID:

text Copy

0193f2a4-1b2c-7d3e-8f4a-5b6c7d8e9f0a

6.2. Вебхук

Для асинхронной задачи можно указать:

Поле	Тип	Описание
`webhook_url`	string	URL уведомления
`webhook_method`	`GET` или `POST`	по умолчанию `GET`
`webhook_data`	string или object	пользовательские данные вебхука

Пример:

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "webhook_url": "https://client.example.com/scrape-callback",
  "webhook_method": "POST",
  "webhook_data": {
    "order_id": "A-10042"
  }
}

Для POST API отправляет:

json Copy

{
  "status": 200,
  "response_id": "0193f2a4-1b2c-7d3e-8f4a-5b6c7d8e9f0a",
  "request_url": "https://client.example.com/scrape-callback",
  "status_message": "OK",
  "webhook_data": {
    "order_id": "A-10042"
  }
}

Ошибки доставки вебхука логируются, но не изменяют результат задачи.

6.3. Получение результата

bash Copy

curl "$BASE_URL/tasks/result/$RESPONSE_ID"

Эндпоинт не требует авторизации и возвращает сырое содержимое результата.

Статус	Значение
`200 OK`	задача успешно завершена
`202 Accepted`	задача ещё выполняется
`404 Not Found`	ID не найден
`410 Gone`	результат удалён по истечении срока хранения
`422 Unprocessable Entity`	задача завершилась с ошибкой

При 202:

text Copy

pending

При 404:

text Copy

Not found

При 410:

text Copy

Result expired

При 422:

text Copy

max_restarts_exceeded

Кроме x-debug, этот эндпоинт возвращает x-debug_request с параметрами найденной задачи.

7. Метод `scrape`

Метод загружает одну веб-страницу и возвращает HTML, Markdown или скриншот.

7.1. Параметры

Поле	Тип	Обязательно	По умолчанию	Описание
`task_type`	string	да	—	всегда `scrape`
`url`	string	да	—	полный URL с `http://` или `https://`
`data_format`	string	нет	`raw`	`raw`, `markdown` или `screenshot`
`format`	string	нет	`json`	`json` или `raw`
`waitFor`	string, содержащая JSON	нет	—	условие ожидания
`fullPage`	boolean	нет	`false`	полностраничный скриншот; применяется к `screenshot`
`cdpurl`	string	нет	—	собственный Chrome через CDP

waitFor передаётся именно строкой:

json Copy

{
  "waitFor": "{\"text\":\"Loaded\"}"
}

а не вложенным объектом:

json Copy

{
  "waitFor": {
    "text": "Loaded"
  }
}

7.2. `data_format`

Значение	`format: "json"`	`format: "raw"`
`raw`	JSON с `status`, `headers`, HTML в `body`	HTML напрямую
`markdown`	JSON с Markdown в `body`	Markdown напрямую
`screenshot`	JSON с PNG в Base64-поле `body`	бинарный PNG

7.3. Получить HTML в JSON

bash Copy

curl -X POST "$BASE_URL/tasks/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "scrape",
    "url": "https://example.com",
    "data_format": "raw",
    "format": "json"
  }'

Ответ:

json Copy

{
  "status": 200,
  "headers": {
    "content-type": "text/html; charset=utf-8"
  },
  "body": "<!DOCTYPE html>..."
}

7.4. Получить HTML напрямую

bash Copy

curl -X POST "$BASE_URL/tasks/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "scrape",
    "url": "https://example.com",
    "data_format": "raw",
    "format": "raw"
  }'

Ответ начинается с:

html Copy

<!DOCTYPE html>
<html>

7.5. Получить Markdown

JSON:

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "data_format": "markdown",
  "format": "json"
}

Напрямую:

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "data_format": "markdown",
  "format": "raw"
}

Пример Markdown:

md Copy

# Example Domain

[More information](https://www.iana.org/domains/example)

7.6. Сделать скриншот видимой области

Base64 в JSON:

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "data_format": "screenshot",
  "format": "json",
  "fullPage": false
}

Ответ:

json Copy

{
  "status": 200,
  "headers": {
    "content-type": "text/html; charset=utf-8"
  },
  "body": "iVBORw0KGgoAAAANSUhEUg..."
}

Поле body содержит Base64 без префикса data:image/png;base64,.

7.7. Получить бинарный PNG

bash Copy

curl -X POST "$BASE_URL/tasks/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "scrape",
    "url": "https://example.com",
    "data_format": "screenshot",
    "format": "raw"
  }' \
  --output screenshot.png

Первые восемь байт файла:

text Copy

89 50 4E 47 0D 0A 1A 0A

7.8. Сделать полностраничный скриншот

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com/long-page",
  "data_format": "screenshot",
  "format": "json",
  "fullPage": true
}

Используйте действительно длинную страницу. Для проверки результата декодируйте PNG и убедитесь, что на изображении присутствуют верх и низ страницы.

Для data_format: "raw" параметр fullPage фактически игнорируется и не изменяет HTML-результат.

7.9. `waitFor`

Ожидать текст

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com/dynamic",
  "waitFor": "{\"text\":\"Content loaded\"}"
}

Страница подходит для этого теста только в том случае, если строка отсутствует в первоначальном HTML и добавляется позже.

Ожидать элемент

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "waitFor": "{\"element\":\"#content\",\"checkVisible\":false}"
}

Ожидать видимый элемент

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "waitFor": "{\"element\":\"#content\",\"checkVisible\":true}"
}

Ожидать полную загрузку

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "waitFor": "{\"state\":\"load\"}"
}

Ожидать построение DOM

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com",
  "waitFor": "{\"state\":\"domcontentloaded\"}"
}

Поддерживаемые значения state:

Значение	Описание
`load`	страница и зависимые ресурсы загрузились
`domcontentloaded`	DOM построен, ресурсы ещё могут загружаться

7.10. Собственный Chrome через `cdpurl`

json Copy

{
  "task_type": "scrape",
  "url": "https://example.com/account",
  "cdpurl": "wss://browser.example.com/devtools/browser/9b2c1f0a-..."
}

Требования:

поддерживается ws:// или wss://;
браузер должен быть доступен воркеру всё время выполнения;
задача использует куки, сессии, профиль, отпечаток и прокси этого браузера;
не публикуйте CDP URL: доступ к нему фактически даёт доступ к браузерной сессии.

8. Метод `google_search`

Метод выполняет запрос в Google и возвращает структурированные результаты либо Markdown.

8.1. Параметры

Поле	Тип	Обязательно	По умолчанию	Описание
`task_type`	string	да	—	всегда `google_search`
`url`	string	да	—	полный URL Google Search с параметрами
`format`	`json` или `raw`	нет	`json`	JSON с дополнительной информацией или результат напрямую
`data_format`	`json` или `markdown`	нет	`json`	формат поля результата
`page_num`	integer	нет	`1`	количество страниц результатов
`with_html`	boolean	нет	`false`	добавить HTML страниц; только для `format: "json"`
`coordinates`	object	нет	—	`{ "lat": number, "lon": number, "radius"?: number }`
`uule`	string	нет	—	Canonical Name или `lat,lon[,radius]`

8.2. Параметры внутри `url`

Параметр	Пример	Описание
`q`	`q=fastify+nodejs`	поисковый запрос
`hl`	`hl=en`	язык страницы результатов, код из двух букв
`gl`	`gl=us`	страна поиска, ISO-код из двух букв
`tbm`	`tbm=isch`	тип поиска
`udm`	`udm=14`	альтернативный тип поиска
`uule`	`uule=Paris...`	геолокация в URL

Значения tbm:

Значение	Тип
`isch`	изображения
`vid`	видео
`nws`	новости
`shop`	покупки
`bks`	книги
`lcl`	локальные результаты/карты

Значения udm:

Значение	Тип
`2`	изображения
`7`	видео
`8`	вакансии
`12`	новости
`14`	классический веб без AI-ответов
`18`	форумы
`28`	покупки
`36`	книги
`39`	короткие видео
`50`	AI Mode
`56`	чистый веб

8.3. Обычный веб-поиск

bash Copy

curl -X POST "$BASE_URL/tasks/sync" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "google_search",
    "url": "https://www.google.com/search?q=fastify+nodejs&hl=en&gl=us",
    "page_num": 1,
    "format": "json",
    "data_format": "json",
    "with_html": false
  }'

Документированный пример результата:

json Copy

{
  "url": "https://www.google.com/search?q=fastify+nodejs&hl=en&gl=us",
  "html": [],
  "data": {
    "total": 100000,
    "organic": [
      {
        "title": "Fastify",
        "url": "https://fastify.dev/",
        "description": "Fast and low overhead web framework for Node.js"
      }
    ]
  }
}

Если with_html: true, поле html содержит HTML полученных страниц.

8.4. Поиск изображений

json Copy

{
  "task_type": "google_search",
  "url": "https://www.google.com/search?q=modern+furniture&hl=en&gl=us&tbm=isch",
  "format": "json",
  "data_format": "json"
}

Альтернативно:

text Copy

https://www.google.com/search?q=modern+furniture&hl=en&gl=us&udm=2

8.5. Новости

json Copy

{
  "task_type": "google_search",
  "url": "https://www.google.com/search?q=technology&hl=en&gl=us&tbm=nws",
  "format": "json",
  "data_format": "json"
}

8.6. Результат в Markdown

json Copy

{
  "task_type": "google_search",
  "url": "https://www.google.com/search?q=fastify+nodejs&hl=en&gl=us",
  "format": "json",
  "data_format": "markdown"
}

8.7. Геотаргетинг

Через Canonical Name:

json Copy

{
  "task_type": "google_search",
  "url": "https://www.google.com/search?q=pizza&hl=en&gl=us",
  "uule": "New York,New York,United States"
}

Через координаты:

json Copy

{
  "task_type": "google_search",
  "url": "https://www.google.com/search?q=pizza&hl=en&gl=us",
  "coordinates": {
    "lat": 40.7128,
    "lon": -74.006,
    "radius": 10
  }
}

Или:

json Copy

{
  "task_type": "google_search",
  "url": "https://www.google.com/search?q=pizza&hl=en&gl=us",
  "uule": "40.7128,-74.0060,10"
}

Если радиус не указан, для uule с координатами используется радиус 200 км.

9. История задач

bash Copy

curl "$BASE_URL/task_history?task_type=scrape&from=2026-01-01&to=2026-12-31&limit=50&offset=0" \
  -H "Authorization: Bearer $API_KEY"

Параметр	Тип	По умолчанию	Описание
`task_type`	string	—	фильтр по методу
`from`	DateTime	—	нижняя граница `add_datetime`
`to`	DateTime	—	верхняя граница `add_datetime`
`limit`	integer	`100`	число записей
`offset`	integer	`0`	смещение

Ответ:

json Copy

[
  {
    "response_id": "0193f2a4-1b2c-7d3e-8f4a-5b6c7d8e9f0a",
    "add_datetime": "2026-07-31 14:00:20.403",
    "finish_datetime": "2026-07-31 14:00:27.996",
    "task_type": "scrape",
    "params": {
      "task_type": "scrape",
      "url": "https://example.com",
      "format": "json"
    },
    "price": 0.0005,
    "mime_type": "application/json",
    "error": ""
  }
]

10. Основные ошибки

HTTP-статус	Причина
`400 Bad Request`	неверные параметры, неизвестный или отключённый `task_type`, тело больше 10 000 байт
`401 Unauthorized`	отсутствует или неверна авторизация
`402 Payment Required`	недостаточно средств
`408 Request Timeout`	синхронное ожидание закончилось; задача может продолжаться
`410 Gone`	результат удалён по сроку хранения
`422 Unprocessable Entity`	задача завершилась с ошибкой
`503 Service Unavailable`	инфраструктура не готова; относится к readiness-проверке

Пример ошибки в JSON:

json Copy

{
  "error": "Insufficient balance"
}

При format: "raw" API может вернуть только текст:

text Copy

Insufficient balance

Всегда проверяйте:

HTTP-статус API;
Content-Type;
x-debug.status_code;
x-debug.response_id;
x-debug.price;
для Scrape JSON — отдельный status целевой страницы.

11. Служебные эндпоинты

Авторизация не требуется.

`GET /health`

bash Copy

curl "$BASE_URL/health"

json Copy

{
  "status": "ok",
  "ts": 1747983214000
}

`GET /health/ready`

bash Copy

curl "$BASE_URL/health/ready"

Успешный ответ:

json Copy

{
  "status": "ready",
  "deps": {
    "redis_streams": true,
    "redis_cache": true,
    "clickhouse": true,
    "s3": true
  }
}

Если зависимость недоступна, эндпоинт возвращает 503 и status: "degraded".

12. Рекомендации по интеграции

Используйте синхронный эндпоинт для коротких задач и асинхронный — для долгих или массовых.
При 408 не создавайте сразу дубликат задачи: сохраните response_id и запросите результат позже.
Не считайте внешний HTTP 200 подтверждением того, что целевой сайт тоже ответил 200.
Не полагайтесь на фиксированную цену в коде; читайте x-debug.price.
Для PNG с format: "raw" сохраняйте ответ как бинарный файл.
Для PNG с format: "json" декодируйте Base64 из верхнеуровневого body.
Для waitFor.text используйте строку, отсутствующую в исходном HTML и появляющуюся без действий пользователя.
Не используйте внешние demo-сайты как постоянные фикстуры: их содержимое и доступность могут измениться.
Защищайте API-ключи, пароли, webhook URL и CDP URL.

Browser API

Браузерные отпечатки

Unlocker APIСкоро

Каталог программ

Блог

How-to

Демо капч