Enterprise Crawler

Crawler - это управляемая очередь, в которую вы отправляете URL и из которой получаете результаты. Три шага жизненного цикла - Setup (настройка очереди), Push (постановка URL в очередь), Pull (получение результатов) - описаны ниже по порядку.

Setup

Создайте именованную очередь в вашей панели управления. Каждый crawler вмещает до 100K URL. Создавайте по одной очереди на каждую задачу - они не разделяют состояние. При создании вы выбираете:

• Уникальное имя (выбираете вы: product-monitor, news-feed и т. д.)
• Режим доставки: либо callback URL (Crawlbase отправляет POST с каждым результатом на этот webhook), либо Cloud Storage (результаты сохраняются автоматически, и вы получаете их через Storage API по собственному расписанию). Выбирается один раз при создании; два режима взаимоисключающие - один и тот же crawler не делает и то, и другое.
• Тип токена (Normal или JavaScript)
• Лимит параллельности (по умолчанию 20, можно повысить по запросу)

Push

Отправляйте URL в очередь crawler-а. Push сразу возвращает rid, чтобы ваш клиент мог продолжить работу; сам обход выполняется в фоне с настроенной для crawler-а параллельностью. Передайте callback=true, чтобы запрос ушёл в очередь вместо inline-выполнения.

curl 'https://api.crawlbase.com/?token=YOUR_TOKEN&crawler=product-monitor&callback=true&url=https%3A%2F%2Fexample.com%2Fp%2F12345'

from crawlbase import CrawlerAPI

api = CrawlerAPI({'token': 'YOUR_TOKEN'})
res = api.push(
    'https://example.com/p/12345',
    {'crawler': 'product-monitor'}
)
print(res['rid'])

const { CrawlerAPI } = require('crawlbase');
const api = new CrawlerAPI({ token: 'YOUR_TOKEN' });

const res = await api.push(
  'https://example.com/p/12345',
  { crawler: 'product-monitor' }
);
console.log(res.rid);

Ответ на push небольшой - это просто подтверждение того, что URL поставлен в очередь.

{ "rid": "a1B2c3D4e5F6" }

Pull

Как завершённые обходы доходят до вас. Два канала, выбираемые один раз при создании crawler-а:

Webhook

Если crawler был создан с callback URL, Crawlbase отправляет POST с каждым результатом на этот webhook в момент завершения обхода. Тело - в теле запроса, метаданные - в заголовках запроса. Никакого опроса, никакого состояния на стороне клиента.

# POST https://your-app.com/webhook
# Content-Type: text/html  (or application/json if scraper used)
# pc_status: 200
# original_status: 200
# rid: a1B2c3D4e5F6
# url: https://example.com/p/12345

…

Ваш webhook должен:

• Быть публично доступным с серверов Crawlbase.
• Принимать POST и отвечать 200, 201 или 204 в течение 200 мс.
• Будьте идемпотентны по rid: дубликаты доставки возможны при повторных попытках.
• Подтверждайте получение до обработки - запускайте работу async, если она занимает больше времени, чем окно ответа.

Форма тела зависит от параметра format, который вы установили при push:

Оба формата приходят сжатыми gzip (Content-Encoding: gzip) - ваш обработчик должен распаковать данные перед разбором. Исключение - webhook-и Zapier, которые не умеют читать gzip-сжатые тела; Crawlbase определяет callback URL Zapier и пропускает сжатие.

Тестирование. Когда вы впервые настраиваете обработчик и хотите изучить точную структуру payload для реального URL, создайте crawler в режиме Storage параллельно с webhook-вариантом и отправляйте одни и те же URL в оба. Получайте данные из Cloud Storage по RID, и у вас будет зафиксированный эталон для сравнения с тем, что приходит на webhook - это полезно для отлова ошибок распаковки и обработки метаданных до того, как они попадут в продакшен-трафик.

Мониторинг-бот. Crawlbase периодически опрашивает ваш webhook, чтобы детектировать сбои. Если бот не может достучаться до вашего endpoint или вы перестали возвращать 2xx, crawler сам приостанавливается автоматически и возобновляет работу, как только endpoint снова отвечает. Проба — обычный POST с JSON-телом, отличимый по User-Agent:

POST https://your-app.com/webhook
User-Agent: Crawlbase Monitoring Bot 1.0
Content-Type: application/json

{ "monitor": true }

Воспринимайте такие запросы как no-op и возвращайте 200. Не обрабатывайте их как результаты обхода - реального RID, по которому можно действовать, нет.

Защита endpoint-а. Путь со случайной строкой (yourdomain.com/2340JOiow43djoqe21rjosi) на практике уже даёт большую часть защиты - такой URL вряд ли будет обнаружен. Для подстраховки добавьте один или несколько следующих способов:

• Токен в query-string: ?token=…, который webhook проверяет перед приёмом тела.
• Кастомный заголовок, отправляемый через callback_headers при push (например, X-Webhook-Token|s3kret) и проверяемый на стороне сервера.
• Отклоняйте всё, что не POST.
• Отклоняйте всё, где отсутствуют ожидаемые заголовки метаданных (Pc-Status, Original-Status, rid).

Мы не рекомендуем использовать allowlist по IP - Crawlbase отправляет запросы со множества IP-адресов, и их набор меняется без предупреждения.

Cloud Storage

Если crawler был создан с режимом доставки Storage, каждый результат автоматически сохраняется в Cloud Storage - никакого флага на push, никакого webhook. Ваш потребитель получает результаты по собственному расписанию через Storage API. Используйте этот режим, когда обработка ниже по конвейеру идёт пакетно, когда вы не можете запустить HTTPS endpoint или когда вам нужен стабильный URL для каждой обойдённой страницы.

Отправляйте push так же, как и для crawler-а в режиме webhook - единственное отличие в том, куда попадает результат. Как только обход URL завершится, получите данные по RID:

# Single fetch by RID
curl 'https://api.crawlbase.com/storage?token=YOUR_TOKEN&rid=a1B2c3D4e5F6'

# Or batch-drain up to 100 RIDs at once with auto_delete=true
# so storage stays small.
curl -X POST 'https://api.crawlbase.com/storage/bulk?token=YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "rids": ["RID1","RID2","RID3"], "auto_delete": true }'

Чтобы узнать, когда результат готов, либо опрашивайте Find Job по конкретному RID, либо следите за Stats по счётчикам queued / completed, либо просто пакетно вычитывайте /storage/bulk по расписанию и пусть «RID not found» подсказывает, что ещё в обработке.

Management API

Небольшой REST-интерфейс для мониторинга и управления вашими crawler-ами - получение статистики, очистка очереди, пауза/возобновление, поиск или удаление отдельной задачи по RID. Все endpoint-ы находятся по адресу /crawler/<TOKEN>/... и аутентифицируются по токену в пути (токен в query-string не требуется).

Stats

Сводка по всем вашим crawler-ам: параллельность, глубина очереди, количество завершённых/неуспешных задач и разбивка по истории.

# All-time summary
curl 'https://api.crawlbase.com/crawler/YOUR_TOKEN/stats'

# Same, filtered to a date range (YYYY-MM-DD bounds, inclusive)
curl 'https://api.crawlbase.com/crawler/YOUR_TOKEN/stats?history_from=2026-04-01&history_to=2026-04-30'

Очистка crawler-а

Немедленно очищает очередь crawler-а - все ещё не обработанные URL удаляются. Используйте это, чтобы восстановиться после неконтролируемого продьюсера или очистить пакет, который больше не нужно обрабатывать. Откатить нельзя.

curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/purge'

Удаление одной задачи

Удаляет один URL из очереди по его RID - идентификатору запроса, возвращённому при push URL.

curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/delete_job?rid=YOUR_RID'

Поиск задачи по RID

Узнайте, на какой стадии запрос. Возвращает QUEUED с метаданными очереди, если он ещё ожидает, или NOT_QUEUED, если он уже обойдён (или так и не попал в очередь).

curl 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/find_by_rid/YOUR_RID'

{
  "status": "QUEUED",
  "request_info": {
    "rid": "YOUR_RID",
    "url": "YOUR_URL",
    "retry": 3,
    "created_at": 1600494969.189415
  }
}

{
  "status": "NOT_QUEUED",
  "request_info": {
    "rid": "YOUR_RID"
  }
}

Pause и unpause

Остановите crawler от взятия новой работы, не теряя его очередь. Push-нутые URL продолжают становиться в очередь, но crawler перестаёт их обрабатывать, пока вы не снимете паузу. Полезно для технических окон или для отступления, когда нижестоящая система нездорова.

# Pause - stops the crawler picking up new work
curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/pause'

# Unpause - resumes processing
curl -X POST 'https://api.crawlbase.com/crawler/YOUR_TOKEN/product-monitor/unpause'

Параметры

Когда использовать Crawler, а когда API

• Crawler: всякий раз, когда у вас более нескольких сотен URL для обработки, особенно на долгих горизонтах времени. Очередь сама занимается ретраями, расписанием и параллелизмом.
• Crawling API напрямую: когда результат нужен сразу: рендеринг страницы для пользовательского запроса, AI-агент, получающий контекст, и т. п.