Enterprise Crawler

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

Setup

Создайте именованную очередь в вашей панели управления. Каждый crawler вмещает до 100 тыс. 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 отправляет push с множества 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. Все endpoints располагаются по пути /crawler/<TOKEN>/... и аутентифицируются токеном в пути (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-агент, забирающий контекст, и т. п.