API-ключ и документация Serper: от входа в аккаунт до первого результата
У Serper нет отдельного сайта с документацией: её заменяет песочница, а ключи можно только создавать, переименовывать и сбрасывать. На основе 34 реальных вызовов разбираем параметры, ошибки и ротацию ключей.

Почти все, кто ищет «serper api key», «serper api docs» или «serper api login», упираются в одно и то же. У Serper нет отдельного сайта с документацией. 5 ноября 2026 г. адрес serper.dev/docs возвращал 404. Документацию на деле заменяет песочница — страница, которой можно пользоваться только после входа в аккаунт. Правила параметров, стоимость в кредитах и примеры кода хранятся в JavaScript этой страницы.
Мы изучили публичные страницы serper.dev и их фронтенд-скрипты. Затем в тот же день с 00:18 до 00:54 по сингапурскому времени отправили 34 реальных запроса к поисковому API EveryInfra. Двадцать один запрос вернул результаты, и вместе они стоили $0,015269. Остальные 13 были намеренными ошибками: ключ в неверном заголовке, превышение лимита запросов и один пустой результат. Все они стоили $0.
Это руководство сравнивает не цены, а путь до работающего вызова. Сколько шагов отделяет регистрацию от первого результата? Где хранится ключ, сколько ключей можно создать и что делать после утечки?
В нём q, gl, hl, num, page и type сопоставлены с нашими параметрами. Мы показываем реальные тела ошибок. Также показано, куда вставить ключ в Python, n8n и MCP-клиентах. Цены разобраны в трёх наших прошлых статьях о Serper, ссылки на них есть в первом разделе.

О чём это руководство и где искать цены
Цены в одной строке: четыре пакета Serper стоят от $0.30 до $1.00 за 1 000 кредитов и сгорают через 6 месяцев. Веб-поиск EveryInfra стоит $0.000694 за вызов ($0.694 за 1 000), без срока действия. Стоимость 1 000 запросов разобрана в статье «Serper API Alternative: Pricing, Free Tier, Real Tests». На сколько хватит 2 500 бесплатных запросов, читайте в статье «Serper API Free Tier». Четыре пакета по месяцам разобраны в статье «Serper API Pricing Explained».
Эта статья для разработчиков, которые пользуются Serper или собираются его попробовать. Речь в ней идёт только о настройке и отладке. Вы узнаете, где взять ключ и как его передавать. Также вы узнаете, где найти правила параметров, что делать при ошибке вызова и как заменить утёкший ключ.
По Serper мы использовали только публичные материалы: главную страницу, страницы регистрации и входа, условия использования, политику конфиденциальности и JavaScript, который эти страницы загружают в браузер любого посетителя. Мы не создавали аккаунт Serper, не использовали ключ Serper и не обращались к поисковому API Serper. Поэтому всё, что сказано о том, «что видно после входа», взято из текста этих скриптов или из публичных сторонних публикаций, и каждый раз мы указываем источник. Все цифры по EveryInfra получены из реальных ответов 5 ноября 2026 г.
Сравнительная таблица: ключ, документация и первый запрос
В таблице только факты, которые можно проверить. Столбец Serper составлен по страницам и скриптам serper.dev, просмотренным 5 ноября 2026 г. Столбец EveryInfra основан на документации, странице тарифов, файле OpenAPI, публичном каталоге и наших реальных вызовах. Документацию, страницу тарифов и файл OpenAPI мы перечитали 5 ноября 2026 г. в 01:25 по сингапурскому времени и сохранили копии.
| Пункт | Serper | EveryInfra |
|---|---|---|
| Регистрация | Имя, email и пароль, а также антибот-проверка; после регистрации нужно подтвердить email | По email либо через GitHub или Google |
| Вход | Email и пароль; по желанию 2FA через приложение-аутентификатор | Как при регистрации |
| Бесплатное использование | 2 500 запросов, без банковской карты | Поставьте звёзды двум репозиториям на GitHub и получите пробные кредиты на сумму $1 со сроком действия 24 часа |
| Где находится ключ | Страница API Keys в личном кабинете | Раздел API Keys в консоли; полный ключ показывается один раз, при создании |
| Ключей на аккаунт | Несколько, у каждого своё имя | Несколько, по окружениям или задачам |
| Управление ключами | Создание, переименование, копирование, сброс | Создание, ограничение по продуктам, отключение, список разрешённых IP, ротация |
| Заголовок авторизации | X-API-KEY: <key> (в варианте с GET apiKey передаётся в URL) | Authorization: Bearer <key> |
| Эндпоинт | https://google.serper.dev/<type> | https://api.everyinfra.com/api/v1/search |
| Где документация | Песочница (после входа); сайта с документацией нет | /docs, /llms.txt, /openapi.json и бесплатный каталог инструментов |
| Машиночитаемая спецификация | OpenAPI и llms.txt не найдены | OpenAPI 3.0.3 с 61 путём, llms.txt, JSON-каталог инструментов |
| MCP | От Serper нет; есть локальные серверы от сообщества | Удалённый MCP-сервер по адресу https://api.everyinfra.com/mcp |
| Формат ошибки | {"message": "...", "statusCode": 403} (по сторонним публикациям) | {"error": {"code", "message", "fault", "retryable", "next_steps", ...}} |
Важнее всего три строки. Первая из них: «Где документация». Serper размещает параметры, примеры кода и стоимость в кредитах на интерактивной странице, для которой нужен вход. Человеку это удобно, но ИИ-ассистенту для программирования нужен дополнительный шаг, чтобы её прочитать. Вторая строка: «Управление ключами».
На странице ключей Serper четыре действия, удаления среди них нет. Ограничить, что может делать отдельный ключ и откуда им можно пользоваться, нельзя. Третья строка: заголовок авторизации. Два API используют разные заголовки, и именно эту замену забывают чаще всего. В нашем тесте запрос с действующим ключом, переданным в X-API-KEY, получил ответ с кодом 401.
Как зарегистрироваться и войти в Serper API
На странице регистрации Serper написано «Create an account» и «Create a free account, no credit-card needed.» В форме три обязательных элемента: полное имя (имя и фамилия), email и пароль (serper.dev/signup, просмотрено 5 ноября 2026 г.). Под формой находится антибот-проверка, и кнопка «Create account» срабатывает только после её прохождения. Скрипт страницы отправляет вместе с запросом два токена этой проверки. После регистрации открывается страница с текстом «Please verify your email account» и вариантами отправить письмо повторно или выйти. По рабочей ссылке открывается «Your email has been verified», а по устаревшей — «The verification link is invalid or has expired».

Страница входа называется «Log in to your account». На ней есть поля email и пароля, «Remember me» и «Forgot password?» (serper.dev/login). Если включить двухфакторный вход в Settings, нужно будет ещё ввести код из приложения-аутентификатора. Текст в настройках гласит: «Scan the QR code below with your authenticator app». Входа через Google или GitHub в скриптах регистрации и входа мы не нашли.
Таким образом, для «serper api login» доступен только один способ входа: email и пароль. Одна небольшая деталь объясняет многие результаты поиска. Если открыть serper.dev/api-keys без входа, страница покажет форму входа. Поэтому результат на первой позиции по запросу «serper api login» часто называется «Log in to your account», но ведёт на /api-keys.
В условиях использования Serper указано «Updated on May 29, 2024». Для аккаунтов важны два правила. Первое запрещает пользователям «Register more than one account at any point in time». Значит, дополнительные аккаунты ради лишних бесплатных запросов нарушают условия.
Второе запрещает «Attempt to circumvent any restrictions or limits placed on your Serper API key or account». Также в условиях сказано, что Serper является сервисом для бизнеса (B2B). В политике конфиденциальности указано «Date Last Reviewed: 5 November 2025» и сказано, что Serper собирает журналы доступа и журналы активности.
Регистрация в EveryInfra начинается с кнопки «Start free» в правом верхнем углу сайта. На странице одно поле email и необязательный реферальный код, затем кнопки «Continue with GitHub» и «Continue with Google». Новый аккаунт мы тоже не создавали, поэтому шаги после регистрации описаны по странице и документации. В разделе Быстрый старт сказано, что после регистрации вы создаёте API-ключ в консоли и что полный ключ показывается только один раз.

Основная разница в настройке сводится к одному шагу. После регистрации в Serper нужно открыть ссылку подтверждения из письма и затем войти по email и паролю. В EveryInfra можно продолжить через GitHub или Google и не заходить в почту. Чтобы получить пробные кредиты EveryInfra на сумму $1, нужно зайти на GitHub и поставить звёзды двум репозиториям, но этот шаг нужен для получения кредитов, а не ключа. Если настройку выполняет ИИ-ассистент, каждый шаг с почтой требует участия человека и останавливает процесс.
Где находится API-ключ Serper и что с ним можно делать?
Ключ Serper находится на странице API Keys в личном кабинете. Страница называется «API Keys», а её подзаголовок гласит: «Your keys to unlock the power of Serper». Скрипт страницы обращается к трём эндпоинтам для работы с аккаунтом — они позволяют получить список ключей, создать ключ и переименовать его. У ключа обязательно должно быть имя: если оставить поле пустым, форма выдаст «Name is required».
У каждого ключа есть также действие «Reset». В диалоге сброса написано: «Are you sure you want to reset this API key? This action cannot be undone and any applications using this key will stop working.» После сброса страница сообщает: «The old API key is not valid anymore. Replace it with the new one.»
На странице есть и кнопка копирования с сообщением «API key copied to clipboard». Значит, полный ключ остаётся виден в личном кабинете, и любой, у кого есть ваши данные для входа, может позже скопировать его снова. В скрипте нет эндпоинта для удаления ключа. Нет в нём и настроек, позволяющих ограничить ключ отдельными продуктами, лимитом расходов или списком IP-адресов, с которых его можно использовать.
На странице Settings доступны настройки имени, пароля, двухфакторной аутентификации и платёжной карты. Страница «Activity logs» показывает последние запросы в столбцах Time, Query, Type, Page, Num, Credits и Response time (ms). Её можно фильтровать по ключу. Переключатель «Anonymize queries» отключает сохранение текста запросов в журнале.
| Действие | Serper (скрипт страницы API Keys) | EveryInfra (документация, страница тарифов, OpenAPI) |
|---|---|---|
| Создание | Да, имя обязательно | Да, по одному на окружение или задачу |
| Переименование | Да | Да (PATCH /portal/api/keys/{key_id} в OpenAPI) |
| Снова посмотреть полный ключ | Кнопка копирования на странице | Полный ключ показывается только один раз: при создании |
| Сброс или ротация | Да, старый ключ сразу перестаёт работать | Да, только в консоли |
| Отключить без удаления | Не обнаружено | Да, после этого вызовы возвращают 401 |
| Удаление | Не обнаружено | Ключи, созданные в консоли, можно только отключить; ключи, созданные через API, можно удалить |
| Ограничение доступа по продуктам | Не обнаружено | Да, запрос к заблокированному продукту возвращает 403 capability_denied |
| Список разрешённых IP-адресов | Не обнаружено | Да, только в консоли |
| Журналы по ключу | Да, журналы активности можно фильтровать по ключу | Да, история вызовов в консоли; в OpenAPI есть эндпоинт статистики по ключу |
| Лимит расходов и срок действия ключа | Не обнаружено | Да, spend_limit_usd и expires_at (OpenAPI) |
Отсутствие отдельной функции не делает Serper непригодным. Разработчику с одним ключом для одного скрипта достаточно возможности создавать и сбрасывать ключ. Проблема проявляется при командной работе, наличии нескольких окружений и использовании ИИ-агентов. Допустим, один и тот же ключ хранится на вашем ноутбуке, в CI и в демонстрационном блокноте, которым вы поделились с клиентом.
Если из блокнота утечёт ключ, его сброс в Serper одновременно нарушит работу во всех трёх местах. Если использовать отдельный ключ для каждого окружения, вы отключите только скомпрометированный ключ. В документации EveryInfra это объясняется на примере электрощитка. Один ключ — главный рубильник, а раздел API Keys → Permission limits позволяет отключать отдельные линии (Быстрый старт, раздел об авторизации).
Управление ключами из скрипта: эндпоинты для ключей в файле OpenAPI EveryInfra
Управлять ключами можно не только в консоли. В разделе Account файла OpenAPI EveryInfra перечислен набор эндпоинтов для ключей, и мы изучили его 5 ноября 2026 г. в 01:25 по сингапурскому времени. Вызовы этих эндпоинтов не оплачиваются. Вместе с другими эндпоинтами аккаунта у них общий лимит: 60 запросов в минуту на аккаунт.
Для эндпоинтов чтения нужны права на чтение данных аккаунта. У ключа с полным доступом ко всем продуктам по умолчанию есть права account:read, requests:read и billing:read. Ключ с доступом только к некоторым продуктам получает эти права лишь после того, как владелец аккаунта включит их в консоли. Для эндпоинтов записи требуется право keys:write. По умолчанию оно отключено, и предоставить его может только владелец аккаунта после входа в консоль. Каждое изменение, внесённое с помощью ключа, отображается в уведомлениях консоли.
| Эндпоинт | Что делает | Ограничения в спецификации |
|---|---|---|
GET /portal/api/keys | Показывает для каждого ключа имя, замаскированный префикс, статус, права, лимит запросов в минуту, лимит расходов в USD и время последнего использования | Никогда не возвращает секрет ключа |
POST /portal/api/keys | Создаёт ключ и возвращает его один раз; можно задать ip_allow, expires_at и spend_limit_usd | Ключ, созданный через API, никогда не получает больше прав, чем вызывающий ключ, и никогда не получает право записи; не более 20 ключей на аккаунт в сутки по UTC; ключ с лимитом расходов не может создавать ключи |
PATCH /portal/api/keys/{key_id} | Переименовывает ключ, меняет его заметку или переносит срок действия на более раннюю дату | Только для ключей, созданных через API, или для вызывающего ключа; ключи из консоли можно только отключить |
POST /portal/api/keys/{key_id}/disable | Сразу отключает любой ключ аккаунта | Снова включить его в консоли может только владелец аккаунта |
DELETE /portal/api/keys/{key_id} | Удаляет ключ безвозвратно | Только для ключей, созданных через API, или для вызывающего ключа |
GET /portal/api/keys/{key_id}/usage | Показывает за последние дни успешные и неудачные вызовы и расходы, а также время последнего вызова ключа | Требует requests:read |
Эти поля важны в случае утечки. spend_limit_usd задаёт для одного ключа лимит расходов в USD на весь срок действия. Расходы рассчитываются как списания за вычетом возвратов средств, а лимит никогда не обнуляется. Задайте небольшой лимит для ключа CI или демо-блокнота, чтобы ограничить расходы в случае утечки. expires_at автоматически прекращает действие временного ключа. ip_allow разрешает использовать ключ только с IP-адресов вашего сервера.
В скрипте страницы API Keys в Serper аналогичных настроек мы не нашли. Этот раздел опирается на текст OpenAPI. Мы не создавали тестовые ключи для вызова каждого эндпоинта.
Документация Serper API — это песочница
Сначала мы проверили, есть ли отдельный сайт документации. 5 ноября 2026 г. адреса serper.dev/docs, serper.dev/llms.txt, serper.dev/openapi.json и serper.dev/sitemap.xml возвращали 404. В столбце «Product» в подвале главной страницы есть песочница и Dashboard, а также ссылки на интеграции с Haystack, Jan AI, CrewAI и LangChain. Ссылок «Docs» или «API reference» там нет.
У организации Serper на GitHub, Serper-API, 7 репозиториев. GitHub помечает все эти репозитории как форки других проектов, например Auto-GPT, chat-ui и Perplexica. Ни один из них не является SDK или спецификацией API.
Поэтому под «serper api documentation» на практике подразумевается песочница. Это форма: слева вы выбираете тип результата и вводите запрос, справа получаете результаты и код. Мы прочитали её скрипт и выписали семь фактов, важных при написании кода под этот API.
Во-первых, тип результата указывается в URL, а не в теле запроса. Скрипт подставляет выбранный тип в https://google.serper.dev/<type> и перед отправкой удаляет type из тела запроса. В меню доступны search, images, videos, places, news, shopping, scholar, patents, autocomplete, product-reviews, lens, maps и reviews, причём доступность некоторых типов зависит от аккаунта. Для парсинга веб-страниц используется другой хост: https://scrape.serper.dev.
Инструмент «Resolve links» стоит 0 кредитов. Во-вторых, у параметров есть значения по умолчанию, и скрипт отбрасывает любой параметр, равный своему значению по умолчанию. Значения по умолчанию: gl=us, hl=en, page=1, num=10 и autocorrect=true.
В-третьих, в меню количества результатов для обычного поиска теперь один вариант: 10. Для images доступны 10 или 100, для shopping используется 40. В-четвёртых, переключатель «Mini-batch (up to 100 queries)» отправляет список поисковых запросов одним запросом. В-пятых, кредиты. Виджет «Credits: N» в реальном времени показывает стоимость текущего запроса.
В скрипте задана стоимость: 3 кредита для maps и lens, 2 кредита для shopping и product-reviews и 1 кредит для большинства остальных типов. Парсинг веб-страницы стоит 2 кредита, а сложной страницы — 6 или 10 кредитов. В скрипте сказано: «Most webpages typically incur 2 credits, but for harder-to-scrape pages ... the cost can be 6 or 10 credits». Для типа images получение более 10 результатов стоит вдвое дороже.
В-шестых, примеры кода. Панель кода использует библиотеку Postman postman-code-generators с открытым исходным кодом. Список языков в меню берётся непосредственно из результата вызова getLanguageList(), по умолчанию выбран Node.js. Можно выбрать POST или GET.
POST передаёт ключ в заголовке X-API-KEY. GET помещает все параметры и apiKey в URL. Ключ в URL попадает в журналы доступа сервера, историю браузера и журналы прокси. Поэтому используйте POST, кроме случаев, когда ваш инструмент поддерживает только GET.
Пост в сообществе n8n от 26 июля 2025 г. показывает эту ловушку. Пользователь отправил GET-запрос с заголовком и получил ошибку 403. В ответе объяснили, что для GET-запроса ключ нужно передавать в URL, а ключ из заголовка считывается только при POST-запросе (ветка в сообществе n8n).
В-седьмых, локации. В описании поля location сказано «You can find a list of supported locations here» и дана ссылка на api.serper.dev/locations. Мы скачали этот публичный список. В нём 100 029 записей из 240 стран и территорий, включая 48 384 почтовых индекса, 37 208 городов и 4 309 районов. Такая детализация намного выше, чем у поля location в EveryInfra. В нашем каталоге инструментов указано, что нужно передавать «название страны или двухбуквенный код страны; при указании города будет использована соответствующая страна».
| Правило песочницы | Где это видно | Что это значит для вашего кода |
|---|---|---|
| Тип задаётся в URL, а не в теле | https://google.serper.dev/ + тип | Чтобы сменить тип, измените URL |
| Значения по умолчанию gl=us, hl=en, num=10, page=1 | Удаляются из сгенерированного кода | Без параметров: США, английский язык |
| У num для обычного поиска один вариант: 10 | Меню количества результатов | Для большего числа результатов используйте page |
| Стоимость в кредитах зависит от типа | Виджет «Credits: N» | maps и lens стоят 3 кредита |
| До 100 поисковых запросов за один вызов | Переключатель Mini-batch | Кредиты считаются за каждый поисковый запрос |
| GET помещает apiKey в URL | Переключатель GET/POST в панели кода | Используйте POST и заголовок |
| 100 029 местоположений | api.serper.dev/locations | С точностью до города и почтового индекса |
У размещения документации внутри интерактивной страницы есть своя цена, и один поисковый запрос позволил её оценить. В 00:18:40 и 00:19:06 по сингапурскому времени мы выполнили поиск по запросу «serper api documentation» через веб-поиск EveryInfra с location: us и проанализировали первые две страницы, то есть 20 результатов. Только 3 URL относились к домену serper.dev: главная страница, /api-keys (без авторизации там отображается форма входа) и /signup. Среди них не было ни одной страницы документации.
Восемь результатов вели на документацию других проектов: CrewAI, LangChain (три результата, один из них — на старом зеркале), Langflow, Haystack, Sim и Aikeedo. Четыре вели на каталоги API. Оставшиеся пять вели на организацию в GitHub, статью на Medium, видео на YouTube, страницу в каталоге MCP-серверов и главную страницу другого поискового API.
| Источник результатов в топ-20 | Количество | Примеры |
|---|---|---|
| Страницы serper.dev | 3 | Главная, /api-keys, /signup |
| Документация фреймворков и платформ | 8 | docs.crewai.com, reference.langchain.com, docs.haystack.deepset.ai, docs.langflow.org |
| Каталоги и маркетплейсы API | 4 | apitracker.io, apis.io и другие |
| Прочее | 5 | github.com/Serper-API, medium.com, youtube.com |
Для читателей из Великобритании мы провели вторую проверку в 00:45:40 SGT: запрос «serper api key» с location: gb. Первыми двумя результатами снова стали главная страница Serper и /api-keys. Далее шли главная страница другого поискового API, документация CrewAI и документация LangChain. Остальные позиции заняли сравнение на Medium, обзор SERP API, документация Aikeedo и issue в репозитории h2oGPT на GitHub.
Те, кто ищет документацию Serper, чаще всего попадают в документацию какого-нибудь фреймворка, а каждый фреймворк описывает Serper немного по-своему.
Разработчикам, которые просят ИИ-ассистента написать клиентский код, нужна документация, которую ассистент может прочитать без входа в аккаунт. У нас эту задачу решают три публичных файла.
| Файл | Что содержит |
|---|---|
| Каталог инструментов | Все 17 поисковых инструментов с параметрами, значениями по умолчанию, ограничениями, описаниями на трёх языках и ценой; ключ не нужен |
| Файл OpenAPI | Версия 3.0.3 с 61 маршрутом по состоянию на 5 ноября 2026 г. |
/llms.txt | Индекс для языковых моделей; в первом блоке указаны базовый URL, заголовок и примечание о том, что на неверные параметры API возвращает did_you_mean и allowed |
Благодаря этим файлам ассистент может проверить параметры до того, как напишет код, а не угадывать их по памяти. Неверная догадка оборачивается ошибкой 422, как показывают тесты ниже. Правила параметров Serper находятся в песочнице, поэтому ассистенту в основном приходится читать пересказ в документации фреймворков. Например, в документации CrewAI до сих пор сказано, что «n_results» по умолчанию равен 10, тогда как меню обычного поиска в песочнице теперь предлагает только 10.
Параметры из документации Serper API в сравнении с EveryInfra
Коротко: оба API принимают тело запроса в JSON и возвращают JSON. Но названия параметров, способ выбора типа результатов и поля ответа различаются. Перейти, просто сменив URL, не получится. Мы сравнили параметры обычного поиска в скрипте песочницы с параметрами инструмента web в EveryInfra. Источник: бесплатный каталог инструментов, данные на 00:16 SGT 5 ноября 2026 г.
| Параметр Serper | Значение в песочнице | Аналог в EveryInfra | Примечание |
|---|---|---|---|
q | Запрос | q (инструмент web); keyword в каталоге данных | То же название, тот же смысл |
gl | Двухбуквенный код страны, по умолчанию us | location | gl возвращает 422; location работает на уровне страны |
hl | Язык интерфейса, по умолчанию en | Нет в web; language в web/search | hl возвращает 422 |
num | Результатов на странице, 10 для обычного поиска | num, до 10 | То же название |
page | Номер страницы, начиная с 1 | page начинается с 1; каждая страница оплачивается отдельно | То же название |
type | Сегмент URL: search, news, images | Поле tool в теле запроса: web, news, media | type в теле запроса возвращает 422 |
tbs | Период qdr:h/d/w/m/y | after, before (даты) | Преобразуйте в даты |
location | Город, район или почтовый индекс; 100 029 вариантов | location работает на уровне страны | То же название, другой смысл |
autocorrect | Исправление опечаток, включено по умолчанию | Нет | Уберите |
| — | — | site (только один домен) | В Serper используется site: внутри q |
Две строки требуют внимания. Первая касается location. Название одинаковое с обеих сторон, а смысл разный. В Serper location означает точное место, а страну задаёт gl. В EveryInfra location означает страну, а при указании города учитывается соответствующая страна.
Поэтому при переходе с Serper скопируйте значение gl в location, а старое значение location из Serper удалите. Вторая строка касается hl. У инструмента web нет параметра языка. Если он нужен, используйте web/search из каталога данных. Он принимает keyword, country и language и стоит $0.001389, вдвое дороже web.
Меняются и типы результатов. Serper указывает тип в URL. У поиска EveryInfra один эндпоинт, POST /api/v1/search, а поле tool в теле запроса выбирает один из 17 инструментов. Эту таблицу мы составили по текстам каталога. Соответствие означает лишь похожее назначение, а не одинаковые результаты.
| Тип в Serper | Поисковый инструмент EveryInfra | Варианты в каталоге данных |
|---|---|---|
| search | web | web/search, bing/search, duckduckgo/search |
| news | news | google_news/search |
| images, videos | media (kind: image или video) | — |
| places, maps | places | — |
| shopping | shopping | google_shopping/search |
| scholar, patents | scholar (kind: papers или patents) | — |
| autocomplete | suggest | — |
| lens | lens | — |
| webpage | read | — |
| reviews, product-reviews | Нет в поиске | Отзывы с карт и о товарах есть в каталоге данных по платформам |
Поскольку стоимость в кредитах зависит от типа, цена Serper за 1 000 вызовов тоже зависит от типа. В пакете Starter 1 000 кредитов стоят $1.00. Maps и lens расходуют 3 кредита на вызов, поэтому стоят $3.00 за 1 000 вызовов. В пакете Ultimate 1 000 кредитов стоят $0.30, так что maps обходится в $0.90 за 1 000.
Все поисковые инструменты EveryInfra, кроме crosscheck, стоят $0.000694 за вызов. На диаграмме публичные цены за единицу сопоставлены по типам. О размерах пакетов и сроках действия кредитов читайте в статье «Цены Serper API: подробный разбор».
Первый запрос: curl для обоих API
Вот первый запрос к Serper в POST-форме из песочницы. Ключа Serper у нас нет, поэтому мы его не запускали. Мы составили его по скрипту страницы и исходному коду CrewAI.
# Serper: configuration example (not run for this article)
curl -s https://google.serper.dev/search \
-H "X-API-KEY: $SERPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"serper api documentation","gl":"us","hl":"en","num":10}'Вот тот же поиск в EveryInfra. Мы выполнили его в 00:18:40 SGT 5 ноября 2026 г. Он вернул HTTP 200 за 1,55 секунды с 10 результатами, а billing.charged_usd составил 0.000694.
# EveryInfra: run for this article
curl -s https://api.everyinfra.com/api/v1/search \
-H "Authorization: Bearer $EVERYINFRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tool":"web","q":"serper api documentation","location":"us","num":10}'Меняются четыре вещи: URL, заголовок, gl превращается в location, а hl исчезает. Ещё одну деталь легко упустить. В документации параметры указываются на верхнем уровне тела запроса, например {"tool":"web","q":...}. Удалённый MCP-инструмент everyinfra_search ожидает их внутри объекта params, например {"tool":"web","params":{"q":...}}. Работают оба варианта, но смешивать их нельзя. Что происходит при смешивании, показано в разделе о MCP ниже.
Пакетная обработка тоже устроена иначе. Mini-batch в Serper принимает до 100 поисковых запросов в одном вызове API. Поисковый API EveryInfra принимает один поисковый запрос за вызов API. Поэтому пакет из 100 ключевых слов превращается в 100 вызовов API, которые нужно отправить в рамках вашего поминутного лимита. Лимит аккаунта по умолчанию составляет 60 запросов в минуту, так что обработка 100 ключевых слов занимает около двух минут.
Пакет скорости повышает лимит до 1 800 запросов в минуту (тарифы). Стоимость не меняется: $0.000694 за запрос, или $0.0694 за 100. Кроме того, одиночные запросы завершаются ошибкой по отдельности. Неверный параметр в одном запросе вернёт один ответ 422, а остальные 99 всё равно выполнятся.
Поля ответа: organic в сравнении с results
Пример ответа на главной странице Serper представляет собой один большой объект. На его верхнем уровне находятся knowledgeGraph, organic, peopleAlsoAsk и relatedSearches. У каждого результата органической выдачи есть title, link, snippet и position, а у некоторых ещё sitelinks, date и attributes (пример на главной странице serper.dev). Песочница удаляет searchParameters из ответа перед показом результатов, поэтому фактический ответ также содержит переданные параметры запроса. LangChain читает для каждого типа свой ключ: organic для search, news для news, places для places и images для images (исходный код LangChain).
Ответ инструмента web в EveryInfra имеет вид {"id","tool","location","results","billing","quota"}. В каждом результате есть title, url и snippet, а также published, если дата известна. В вызове для страницы 2 в 00:19:06 SGT поле published было у 3 из 10 результатов. Запись каталога данных web/search возвращает больше полей: title, url, text, rank, published_at, image_url и sub_links (каталог данных). В вызове в 00:20:09 SGT поле published_at было у 3 из 10 результатов.
| Назначение | Serper (search) | EveryInfra `web` | EveryInfra `web/search` |
|---|---|---|---|
| Заголовок | organic[].title | results[].title | results[].title |
| Ссылка | organic[].link | results[].url | results[].url |
| Сниппет | organic[].snippet | results[].snippet | results[].text |
| Позиция | organic[].position | Порядок в массиве | results[].rank |
| Дата | organic[].date (не всегда) | results[].published (не всегда) | results[].published_at (не всегда) |
| Панель знаний, похожие вопросы | knowledgeGraph, peopleAlsoAsk | Нет | Нет |
| Стоимость этого вызова | На главной странице сказано, что кредиты списываются за каждый успешный ответ; документированного поля ответа нет | billing.charged_usd | billing.charged_usd |
Последняя строка касается учёта расходов. В FAQ Serper сказано: «Каждый раз, когда вы получаете успешные ответы на запросы, мы списываем кредиты с баланса вашего аккаунта». Когда баланс обнуляется, новые запросы перестают выполняться. Чтобы узнать, сколько вы потратили, нужно открыть Dashboard и Activity logs. Каждый ответ EveryInfra содержит объект billing с полями charged, charged_usd и balance_after_usd.
Пакетное задание может сверить расходы только по ответам. У неудачных и пустых вызовов указано charged: false. Инструмент web не возвращает панели знаний и похожие вопросы. Коду, который зависит от этих полей, нужна новая логика; подробнее об этом в разделе «Когда лучше выбрать Serper».
Тест 1: запрос в стиле Serper без изменений
Самая вероятная ошибка после перехода: сменить URL и заголовок, но оставить старые параметры. Мы допустили эту ошибку намеренно, чтобы посмотреть, что сделает API.
В 00:18:28 SGT мы отправили {"tool":"web","q":"serper api documentation","gl":"us","hl":"en","num":10}. API вернул HTTP 422 за 0,20 секунды. error.code имел значение unknown_param. В message было: «gl is not a parameter of tool web Supported: after, before, location, num, page, q, site».
Список allowed содержал 7 допустимых параметров. В поле next_steps было: «Remove gl; the parameters are listed at catalog_url. Nothing was charged.» API сообщает об одном неизвестном параметре за вызов. Мы удалили gl, оставили hl и отправили запрос снова в 00:18:47 SGT, и вернулась та же ошибка 422 с param: hl.
В 00:19:00 SGT мы написали location как locaton. Ошибка 422 вернулась за 0,11 секунды с did_you_mean: ["location"]. Первый шаг гласил: «Rename locaton to location (did_you_mean), then resend. Nothing was charged.» Второй предлагал открыть тикет, если отправленный параметр в каталоге всё-таки есть.
В 00:19:14 SGT мы добавили в тело запроса "type":"news", и запрос вернул 422, потому что type не является параметром web. В 00:19:20 SGT мы отправили kind: "videos" инструменту media. Ошибка была invalid_value, в allowed значились image и video, а в did_you_mean значилось video.

Эти ошибки нужны для того, чтобы ИИ-ассистент мог сам исправить свой вызов. Код 422 сообщает программе, что повторная попытка не поможет, а allowed и did_you_mean подсказывают ассистенту, что изменить. В HTTP код 422 означает запрос, который сервер понимает, но не может обработать (MDN: 422, определён в RFC 9110, раздел 15.5.21). Это подходит для неверного названия или неверного значения. Тело нашей ошибки не соответствует формату problem+json из RFC 9457. Это наш собственный объект error, и каждое его поле описано в руководстве по самовосстанавливающимся ошибкам API.
Тест 2: без ключа, неверный заголовок и лимиты запросов
В 00:18:21 SGT мы вызвали web без заголовка авторизации. API вернул HTTP 401 за 0,12 секунды с code: unauthorized и message: Missing API key. fault имел значение account, retryable был false, а в next_steps было сказано: «This API key is not accepted; ask the user for a working key (console: API keys). Nothing was charged.» В 00:18:34 SGT мы передали действующий ключ в заголовке X-API-KEY, как принято в Serper. Результат: та же ошибка 401 с тем же сообщением.
О втором результате нужно сказать честно. В ошибке нет подсказки «use Authorization: Bearer instead». Если вы переходите с Serper, поменяйте строку заголовка сами, как показано в таблице выше.
Ключа Serper у нас нет, поэтому мы цитируем публичные посты. В ветке n8n выше показан HTTP 403 с телом {"message":"Unauthorized. Sign up for a free account.","statusCode":403}. Issue CrewAI #633 2024 года называется «Unauthorized Error (403) when Using SERPER_API_KEY».
Причиной оказался ключ от другого сервиса. Для пустого баланса в примечании к коммиту от 23 октября 2026 г. зафиксирован ответ 400 {"message":"Not enough credits"} (neo1415/q #339). В списке задач от 22 октября 2026 г. указано «400 или 403» с пометкой, что это не подтверждено (dbhq-uk/gannet #12). Таблицы кодов ошибок на serper.dev мы не нашли.
С лимитами запросов мы столкнулись и без специальной проверки. У нашего тестового ключа собственный лимит в 10 вызовов в минуту, и им пользуются несколько задач по написанию текстов. Мы получили HTTP 429 четыре раза: в 00:19:55, 00:20:56, 00:22:38 и 00:24:51 SGT. В каждом ответе были code: rate_limited, retry_after в 5, 4, 22 и 9 секунд соответственно, max_retries: 3 и примечание «Nothing was charged.
Retry after retry_after seconds». Наш скрипт после любой ошибки 429 ждал 60 секунд, и каждая следующая попытка проходила успешно. О заголовке читайте в MDN: Retry-After, а о коде 429 в RFC 6585.
| Сценарий | Serper (публичные посты) | EveryInfra (наши тесты) | Списание |
|---|---|---|---|
| Нет ключа или неверный ключ | 403 Unauthorized. Sign up for a free account. | 401 unauthorized, Missing API key | Нет в обоих случаях |
| Неверный заголовок | Для GET ключ передаётся в URL | X-API-KEY возвращает 401 | Нет |
| Нулевой баланс | 400 Not enough credits (запись третьей стороны) | 402 quota_exhausted (по документации) | Нет |
| Неизвестный параметр | Не описано | 422 unknown_param с allowed и did_you_mean | Нет |
| Неверное значение | Не описано | 422 invalid_value с allowed | Нет |
| Лимит запросов | От 50 до 300 запросов в секунду в зависимости от пакета (главная страница) | 429 rate_limited с retry_after | Нет |
| Пустой результат | На главной странице сказано, что кредиты списываются только за успешные ответы | 200, charged: false, reason: empty_result_refunded | Нет |
Для строки о пустом результате мы в 00:20:17 SGT искали несуществующую строку в кавычках. API вернул HTTP 200 с пустым массивом results, billing.charged: false, reason: empty_result_refunded и refund.status: succeeded. Как сверять неудачные и пустые вызовы в собственном учёте, описано в руководстве по сверке возвратов средств за неудачные запросы.
Тест 3: один запрос в десяти странах
Работает ли location после переноса в него значения gl? С 00:22 до 00:26 SGT мы отправляли один и тот же запрос «google search api» в web с num, равным 10. Значения location: us, gb, de, fr, es, mx, br, jp, sg и in. Все десять вызовов вернули HTTP 200 и стоили по $0.000694, всего $0.00694. Вызов для США вернул 9 результатов, остальные вернули по 10.
За основу мы взяли 9 URL из выдачи для США и подсчитали, сколько из них встретилось в каждой другой стране. Сингапур и Великобритания сохранили все 9. Индия, Япония и Франция сохранили 7. Бразилия и Испания сохранили 6. Мексика и Германия сохранили только 5.
В Германии добавились личный сайт на домене .de и видео на YouTube. В Японии добавился qiita.com, в Мексике rapidapi.com. Значит, параметр страны меняет результаты. Англоязычные рынки остаются близки к списку США, а остальные отходят от него дальше, как и следует ожидать при региональном ранжировании.
Этот тест показывает и ограничение. Мы проверяли только уровень страны, потому что location в EveryInfra не детализируется ниже страны. Serper доходит до города и почтового индекса. Если вам нужны «локальные результаты для одного ZIP-кода в Нью-Йорке», инструмент web в EveryInfra с этим не справится.
Выборка к тому же небольшая: один запрос, один вызов на страну. Позиции со временем меняются. Цифры пересечения доказывают, что параметр работает. Долгосрочные различия между странами они не измеряют.
Тест 4: задержка и скорость возврата ошибок
Мы разделили все 34 запроса по исходу и измерили общее время выполнения с помощью curl из Сингапура, включая сетевую задержку. Время выполнения 21 платного запроса составило от 0,98 до 3,48 секунды, медиана — 1,81 секунды. Быстрее всего отработал suggest: 0,98 секунды. Медленнее всего отработал вызов web для Великобритании в 00:45:40 SGT: 3,48 секунды. Пустой результат был получен за 2,12 секунды, поскольку поиск всё-таки выполнялся.
11 отклонённых запросов (401, 422 и 429) вернулись за 0,09–0,20 секунды. Они остановились на проверке авторизации или параметров и до поиска не дошли. На главной странице Serper сказано: «Как правило, все запросы возвращаются за 1–2 секунды». Serper мы не тестировали, поэтому ничего не утверждаем о его скорости.
Диаграмма охватывает первые 29 запросов. Для английской версии статьи мы сделали ещё пять вызовов. С ними медиана по всем 21 платному вызову составляет 1,81 секунды.
| Время (SGT) | Вызов | Результаты | Секунд | Списание |
|---|---|---|---|---|
| 00:45:32 | suggest, «serper api docs» | 8 | 0.98 | $0.000694 |
| 00:45:40 | web, «serper api key», location: gb | 10 | 3.48 | $0.000694 |
| 00:45:51 | web, «SERPER_API_KEY», site: github.com | 10 | 2.67 | $0.000694 |
| 00:47:57 | web, вызов, сформированный приведённой ниже функцией Python из тела запроса Serper | 10 | 2.24 | $0.000694 |
| 00:53:26 | suggest, «serper api login» | 9 | 1.15 | $0.000694 |
Быстрые ошибки помогают тому, кто пишет код. Неверный параметр не заставляет ждать две секунды. Ответ 422 с исправлением приходит за десятую долю секунды, так что ассистент может исправить запрос и отправить его снова за один шаг. Верно и обратное. Программа, которая при любом ответе с кодом, отличным от 200, повторяет запрос, считая, что сервис занят, зря тратит повторные попытки на ошибки 422. Повторяйте запрос только при ошибках с retryable: true, например 429 и 503.
Тест 5: подсказки, новости и запись каталога данных
Типам autocomplete и news в Serper соответствуют инструменты suggest и news в EveryInfra. В 00:20:01 SGT suggest для «serper api key» вернул 10 записей. У каждой записи есть только title, например «serper api key free», «serper api key pricing», «serper api key crewai» и «get serper api key». Вызов стоил $0.000694.
В 00:21:28 SGT news для «Model Context Protocol» вернул 10 результатов, у каждого было поле published. Значения были относительными, например «17 hours ago» и «2 days ago». Чтобы сортировать по дате в базе данных, пересчитайте их относительно времени запроса. Или используйте google_news/search из каталога данных: он возвращает published_at в UTC в формате ISO 8601 за $0.000792.
В 00:20:09 SGT мы попробовали запись каталога данных web/search для «serper api key» с keyword, country: us и language: en. Она вернула 10 результатов за $0.001389. Эта запись позволяет задать язык результатов. Она возвращает поля text и rank в той же структуре, что и результаты поиска по другим платформам каталога. Это удобно, если вы храните веб-результаты рядом с данными других платформ. Если вам нужны только веб-результаты без настройки языка, инструмент web стоит вдвое дешевле.
Первыми тремя результатами web/search стали главная страница Serper, главная страница другого поискового API и serper.dev/api-keys. Седьмым был пост в сообществе Clay о том, как найти ключ в панели Serper. Тот же запрос через web мы не выполняли, поэтому порядок результатов не сравниваем. Не рассчитывайте, что эти два варианта вернут одинаковый список.
Ключ в Python: названия переменных различаются
Храните ключ в переменной окружения, а не в коде. Об этом говорят и The Twelve-Factor App, и OWASP Secrets Management Cheat Sheet. Для локальной работы python-dotenv читает файл .env, и этот файл нужно внести в .gitignore. Проблема в том, что у Serper нет собственного SDK, поэтому каждый фреймворк выбирает своё название переменной. Мы изучили актуальный исходный код и документацию четырёх фреймворков.
| Фреймворк | Переменная для Serper | Источник |
|---|---|---|
LangChain (GoogleSerperAPIWrapper) | SERPER_API_KEY | Справочник LangChain |
CrewAI (SerperDevTool) | SERPER_API_KEY | Документация CrewAI |
Haystack (SerperDevWebSearch) | SERPERDEV_API_KEY | Исходный код Haystack, документация |
| LiteLLM (поиск) | SERPER_API_KEY | Документация LiteLLM |
Haystack добавляет к названию «DEV». Если на одной машине работают и LangChain, и Haystack, задайте две переменные или напишите в Haystack Secret.from_env_var("SERPER_API_KEY"). Названия параметров тоже различаются. SerperDevTool в CrewAI использует country, locale и n_results, а в исходном коде они сопоставляются с gl, hl и num. Инструмент поддерживает только типы search и news.
Мы читали ветку main на следующий день после релиза 1.15.35 от 3 ноября 2026 г. LangChain использует k, gl, hl и type. Haystack использует top_k и search_params. Так что для каждого подключаемого фреймворка придётся разбираться со своими названиями переменной и параметров.
Для EveryInfra в Python не нужен специальный пакет. Достаточно Requests. Если в вашем коде уже есть тела запросов в стиле Serper, небольшая функция может преобразовать их в тела запросов EveryInfra. Мы запустили функцию ниже в 00:47 SGT 5 ноября 2026 г.
На входе было {"q": "serper api key rotate", "gl": "gb", "hl": "en", "num": 10, "tbs": "qdr:y", "autocorrect": true}. На выходе получилось {"tool": "web", "q": "serper api key rotate", "location": "gb", "num": 10, "page": 1, "after": "2025-11-04"}. Вызов вернул HTTP 200 с 10 результатами за 2,24 секунды и стоил $0.000694. У всех 10 результатов дата published была позже 4 ноября 2025 г., значит, фильтр after сработал.
import datetime as dt, os, requests
URL = "https://api.everyinfra.com/api/v1/search"
TYPE_TO_TOOL = {"search": "web", "news": "news", "images": "media", "videos": "media",
"places": "places", "maps": "places", "shopping": "shopping",
"scholar": "scholar", "patents": "scholar", "autocomplete": "suggest",
"lens": "lens", "webpage": "read"}
TBS_DAYS = {"qdr:h": 1, "qdr:d": 1, "qdr:w": 7, "qdr:m": 31, "qdr:y": 366}
def from_serper(serper_type, body, today=None):
"""Turn a Serper-style request into an EveryInfra search body."""
tool = TYPE_TO_TOOL[serper_type]
out = {"tool": tool, "q": body["q"]}
if tool == "web":
if "gl" in body:
out["location"] = body["gl"] # country code moves to location
out["num"] = min(int(body.get("num", 10)), 10)
out["page"] = int(body.get("page", 1))
if body.get("tbs") in TBS_DAYS:
today = today or dt.date.today()
out["after"] = (today - dt.timedelta(days=TBS_DAYS[body["tbs"]])).isoformat()
# hl, autocorrect and Serper's city-level location have no web-tool match: dropped
return out
body = from_serper("search", {"q": "serper api key rotate", "gl": "gb", "hl": "en",
"num": 10, "tbs": "qdr:y", "autocorrect": True})
r = requests.post(URL, json=body, timeout=90,
headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"})
data = r.json()
if r.status_code != 200 and not data["error"].get("retryable"):
raise ValueError(data["error"]["next_steps"]) # 401 and 422: fix, do not retry
print(len(data.get("results", [])), data.get("billing", {}).get("charged_usd"))Функция подробно обрабатывает только вариант web. Для media и scholar добавьте kind сами и сначала сверьтесь с каталогом. Вариант qdr:h округляется до одного дня, потому что after принимает дату.
Ключ в n8n: HTTP Request и MCP Client Tool
В n8n нет встроенного узла Serper. Страница интеграции Serper на n8n.io 5 ноября 2026 г. возвращала 404. Пользователи берут универсальный узел HTTP Request. Ключ укажите в учётных данных Header Auth с именем X-API-KEY (учётные данные HTTP Request в n8n).
Выберите метод POST. Ошибка 403 в упомянутой выше ветке возникла при GET-запросе. Настройки ниже соответствуют документации n8n на 5 ноября 2026 г.
Подключить EveryInfra можно двумя способами. Первый: тот же узел HTTP Request. Задайте в Header Auth имя Authorization, а в значении укажите Bearer , пробел и ваш ключ. В URL укажите https://api.everyinfra.com/api/v1/search, а тело скопируйте из примера curl.
Второй способ: узел MCP Client Tool в воркфлоу AI Agent. Укажите эндпоинт https://api.everyinfra.com/mcp, выберите авторизацию Bearer и сохраните ключ в учётных данных. После этого агент получит список инструментов, например everyinfra_search, и сам решит, когда их вызывать.
Для этой статьи мы не запускали n8n, поэтому считайте обе настройки примерами конфигурации по документации n8n. Полный воркфлоу, который запускается каждое утро, описан в руководстве по ежедневному отчёту в n8n.
Ключ в MCP-клиентах: удалённый сервер в сравнении с локальным
У Serper нет собственного MCP-сервера. На GitHub есть серверы от сообщества, например marcopesani/mcp-server-serper (лицензия MIT, 171 звезда, последний push 13 марта 2025 г.) и garylab/serper-mcp-server (39 звёзд, последний push 10 ноября 2025 г.). Оба запускают локальный процесс на вашем компьютере через npx или uvx. Ключ указывается в блоке env конфигурационного файла клиента как SERPER_API_KEY. В итоге ключ хранится открытым текстом в конфигурационном файле на каждой машине, где работает клиент.
У EveryInfra есть удалённый MCP-сервер по адресу https://api.everyinfra.com/mcp. Он использует HTTP-транспорт из спецификации MCP версии 2026-07-28, а ключ передаётся в заголовке Authorization. В Claude Code сервер добавляется одной командой (документация Claude Code по MCP). Для других клиентов см. страницу настройки MCP и руководство по настройке удалённого MCP.
claude mcp add --transport http everyinfra https://api.everyinfra.com/mcp \
--header "Authorization: Bearer $EVERYINFRA_API_KEY"Список инструментов можно получить без ключа. Около 00:21 SGT мы вызвали tools/list без ключа и получили 12 инструментов. everyinfra_search принимает на вход tool (один из 17) и объект params. В 00:21:40 SGT мы намеренно вынесли q за пределы params.
Ответ: HTTP 200 с isError: true и текстом «missing_param: q is required» и «Next steps: Add the required q. Nothing was charged.» В 00:21:58 SGT мы отправили {"tool":"web","params":{"q":"serper api login","location":"us","num":5}}. Запрос вернул 5 результатов, первым был serper.dev/api-keys с заголовком «Log in to your account», а charged_usd составил 0.000694, как и при прямом вызове API.
В спецификации MCP есть раздел об авторизации для удалённых серверов, и в нём рекомендуется OAuth. Сейчас мы используем статический Bearer-ключ. Его может отправить любой клиент, но защищать ключ приходится самостоятельно; об этом следующий раздел. Как выбрать тип поискового инструмента для ИИ-агента, читайте в руководстве по выбору поисковых инструментов для агентов.
Ключ утёк: как заменить его в каждом из сервисов
Начнём с недавнего реального случая. Его описывает отчёт LiteLLM об инциденте от 23 октября 2026 года. 27 мая 2026 года кто-то закоммитил в публичный репозиторий конфигурационный файл с внутренним ключом администратора. Примерно через три часа файл удалили, а ключ внесли в список «на отзыв».
Коммит оставался в публичной истории до 22 октября, а из-за человеческой ошибки ключ так и не отозвали. 10 октября 2026 года злоумышленник воспользовался этим ключом четырёхмесячной давности, который всё ещё работал. Через него он добрался до токена владельца организации на GitHub. 21 октября конвейер релизов LiteLLM опубликовал скомпрометированную версию 1.107.0 (отчёт LiteLLM об инциденте).
| Дата (2026) | Что произошло |
|---|---|
| 27 мая | Конфигурационный файл с ключом администратора попадает в публичный репозиторий |
| 27 мая, примерно через 3 часа | Файл удаляют, ключ вносят в список «на отзыв» |
| С 27 мая по 22 октября | Коммит остаётся в публичной истории, ключ так и не отзывают |
| 10 октября | Злоумышленник использует старый ключ, который всё ещё работает |
| 21 октября | Выходит скомпрометированный релиз 1.107.0 |
Урок в отчёте сформулирован так: «не была проведена ротация потенциально раскрытого ключа». В тот же день Railway сообщила, что третья сторона могла получить доступ к системам, где хранятся переменные окружения клиентов. Компания попросила всех пользователей заменить значения всех переменных окружения, хранящихся в Railway, включая API-ключи (сообщение Railway от 21 октября 2026 года). Правило простое.
Удаление ключа из кода не отключает сам ключ. Старый ключ нужно сделать недействительным на стороне сервиса. Ниже описано, как это сделать в каждом сервисе.
В Serper войдите в аккаунт и откройте API Keys. Найдите утёкший ключ и нажмите «Reset». После подтверждения старый ключ сразу перестаёт работать, а на странице появляется новый. Замените ключ везде, где он использовался.
Если один ключ использовался в нескольких местах, все они перестанут работать одновременно, потому что отключить только одно из них нельзя. Затем откройте Activity logs, отфильтруйте записи по этому ключу и поищите незнакомые запросы. Если вы включили «Anonymize queries», в журнале будут видны количество запросов и кредиты, но не текст запросов.
В EveryInfra отключите утёкший ключ в консоли. После этого вызовы с ним возвращают 401. Это можно сделать и скриптом: ключ с областью доступа keys:write может отправить запрос POST /portal/api/keys/{key_id}/disable. После этого снова включить ключ может только владелец аккаунта в консоли. Создайте новый ключ на замену. Если вы завели отдельный ключ для каждого окружения, остальные окружения продолжат работать.
Ротацию, области доступа и список разрешённых IP можно изменить только в консоли, поэтому ключ не может менять собственные настройки (Быстрый старт, раздел об аутентификации). Затем проверьте в истории вызовов запросы и расходы за время утечки. GET /api/v1/account тоже показывает использование за последние 24 часа, и этот вызов бесплатный.
К утечке можно подготовиться заранее. Разделите ключи так:
| Где работает ключ | Какие настройки использовать |
|---|---|
| Продакшен-сервер | Отдельный ключ, в списке разрешённых IP только адреса сервера |
| CI | Отдельный ключ с небольшим лимитом расходов в USD |
| Демо-блокнот или общий тест | Отдельный ключ с небольшим лимитом расходов и сроком действия |
Тогда при утечке любого ключа вы отключаете только его. Остальные продолжают работать, а потери не превысят лимит этого ключа.
Никто другой не заметит утечку за вас. Сканирование секретов GitHub находит в репозиториях ключи известных форматов и оповещает сервисы-партнёры, чтобы те их отозвали. 5 ноября 2026 года мы насчитали в списке поддерживаемых шаблонов 207 провайдеров, и ни Serper, ни EveryInfra среди них нет. В релизе TruffleHog v3.99.8 от 2 ноября 2026 года есть детекторы для трёх других SERP-сервисов, но не для Serper. В правилах Gitleaks по умолчанию их тоже нет.
13 октября 2026 года GitHub добавил два типа ключей Anthropic в стандартную защиту при отправке изменений (история изменений GitHub). 28 октября 2026 года он добавил защиту при отправке изменений на основе ИИ, которая оценивает контекст, а не фиксированные форматы. По умолчанию эта функция выключена (история изменений GitHub). Пока сканер не знает формат вашего ключа, пользователи GitHub Advanced Security могут создать для него собственные шаблоны.
Публичный код показывает, как часто встречается имя переменной. В 00:45:51 по сингапурскому времени мы искали «SERPER_API_KEY» с site: github.com. Все 10 результатов оказались публичными страницами GitHub. Среди них были обращение по поводу ошибки 403 в репозитории CrewAI, обращение в репозитории h2oGPT под названием «configure the serper api key?» и два MCP-сервера от сообщества.
Там же нашлись README блюпринта NVIDIA и запрос на добавление функции в Hermes Agent от 21 июля 2026 года. Само имя переменной в публичном коде встречается постоянно, и это безопасно. Риск появляется, когда рядом с именем в закоммиченном файле .env лежит значение, а ни один сканер по умолчанию это значение не отмечает.
| Шаг после утечки | Serper | EveryInfra |
|---|---|---|
| Отключить старый ключ | API Keys → Reset — сразу | Отключение в консоли, вызовы возвращают 401 |
| Отключить доступ в одном месте, сохранив остальные | Нет, сбрасывается весь ключ | Да, если у каждого окружения свой ключ |
| Ограничить ущерб | Нет лимита расходов для отдельного ключа и ограничений по IP | Области доступа по продуктам, список разрешённых IP, лимит расходов в USD на ключ, срок действия |
| Проверить вызовы за время утечки | Activity logs с фильтром по ключу | История вызовов в консоли, /api/v1/account |
| Автоматическое обнаружение в публичных репозиториях | Нет в правилах GitHub, TruffleHog и Gitleaks по умолчанию | Тоже нет |
Когда Serper подходит лучше
Вот случаи, в которых Serper подходит лучше, чем EveryInfra.
Во-первых, локальная выдача по городу, району или почтовому индексу. В списке локаций Serper 100 029 записей вплоть до почтовых индексов, а location в EveryInfra ограничивается страной. Для отслеживания позиций в локальном SEO или проверки выдачи по городам выбирайте Serper. Во-вторых, блоки страницы выдачи: панели знаний, «People also ask» и связанные запросы. Serper возвращает их в полях knowledgeGraph, peopleAlsoAsk и relatedSearches.
Инструмент web в EveryInfra возвращает только заголовок, ссылку, сниппет и дату. В-третьих, высокая пропускная способность. Пакеты Serper рассчитаны на 50–300 запросов в секунду. Аккаунт EveryInfra по умолчанию допускает 60 запросов в минуту, а с пакетом скорости до 1 800 в минуту (Тарифы). Если нужны сотни запросов за одну секунду, Serper намного сильнее.
В-четвёртых, отзывы на картах и отзывы о товарах. В Serper есть типы поиска reviews, product-reviews и maps. В поиске EveryInfra таких инструментов нет, поэтому для каждой платформы придётся искать подходящую возможность в каталоге данных, а это потребует дополнительных настроек. В-пятых, пакетные запросы — до 100 поисковых запросов в каждом.
Их поддерживает Mini-batch в Serper, а поиск EveryInfra принимает один запрос за вызов. В-шестых, большая кодовая база, уже построенная на полях Serper, которой нужны только результаты на американском английском. Здесь изменения в коде могут обойтись дороже, чем вы сэкономите, так что подождите. Переход стоит рассмотреть, когда вы добавляете поиск в ИИ-агента или хотите один ключ для данных, поиска и других возможностей.
Ограничения: когда эти выводы неприменимы
Во-первых, наши утверждения о личном кабинете Serper основаны на тексте в скриптах страниц, а не на непосредственном изучении экранов интерфейса. Мы не стали описывать функции, которые есть в скрипте, но не отображаются, например типы, доступные только служебным аккаунтам. Серверные функции, которые скрипт не упоминает, мы тоже не видим. Во-вторых, тела ответов с ошибками Serper взяты из сторонних публикаций с июля 2025 по октябрь 2026 года и могли измениться. В-третьих, шаги после регистрации и возможности API-ключей EveryInfra мы описали по сайту, документации, странице тарифов и файлу OpenAPI. Мы не создавали новый аккаунт и не отправляли запрос с ключом с ограниченной областью доступа, чтобы увидеть 403.
В-четвёртых, наши 34 вызова шли через тестовый ключ с лимитом 10 вызовов в минуту, в отличие от обычного аккаунта. В-пятых, тесты выбора региона и задержки основаны на единичных замерах из Сингапура. В-шестых, мы не сравниваем качество и охват результатов.
FAQ
Как настроить API-ключ Serper в приложении?
Задайте его как переменную окружения, затем проверьте, какое имя читает ваш фреймворк. LangChain, CrewAI и LiteLLM читают SERPER_API_KEY. Haystack читает SERPERDEV_API_KEY. Обращение в репозитории h2oGPT под названием «configure the serper api key?» (h2oai/h2ogpt #914) показывает типичную ошибку.
Пользователь вставил ключ туда, где код ожидал имя переменной. Приложение всё равно не заработало и выдало ошибку валидации с требованием другого ключа.
Бесплатный тариф Serper даёт 2 500 запросов в месяц?
На главной странице Serper написано «Get 2,500 free queries», без слов «в месяц». В запросе на доработку Hermes Agent от 21 июля 2026 года это названо «2,500 free queries/month» (NousResearch/hermes-agent #68615). После регистрации проверьте данные в панели управления и не рассчитывайте на ежемесячное обновление лимита. Условия использования также запрещают иметь больше одного аккаунта одновременно. На сколько хватит 2 500 запросов, читайте в статье «Бесплатный тариф Serper API».
Почему CrewAI возвращает 403 Unauthorized с моим ключом Serper?
Сначала проверьте, что ключ получен на serper.dev. В обращении CrewAI № 633 у пользователя был ключ от другого сервиса. Затем убедитесь, что переменная называется SERPER_API_KEY (именно её напрямую читает исходный код CrewAI) и что запрос отправляется методом POST. Если в теле ответа написано «Unauthorized. Sign up for a free account.», ключ неверный или отсутствует. См. обращение CrewAI № 633.
Есть ли полный справочник по Serper API?
5 ноября 2026 года мы его не нашли. serper.dev/docs, /llms.txt и /openapi.json вернули 404, а в организации на GitHub нет SDK. Параметры, типы и стоимость в кредитах описаны в песочнице, которая также генерирует пример кода. Документация фреймворков CrewAI, LangChain, Haystack, LiteLLM и Langflow описывает только отдельные части.
Можно ли войти в Serper через Google или GitHub?
В скриптах регистрации и входа мы не нашли входа через сторонние сервисы. В Serper вход выполняется по email и паролю, двухфакторная аутентификация необязательна. В EveryInfra можно войти по email, через GitHub или Google.
Начало работы: от ключа до первого результата
Чтобы попробовать, зарегистрируйтесь на everyinfra.com. Поставьте звёзды двум репозиториям на GitHub и получите в консоли пробные кредиты на $1, которые действуют 24 часа. Создайте ключ в разделе API Keys, отправьте приведённый выше запрос curl и посмотрите billing.charged_usd в ответе. Чтобы бесплатно посмотреть параметры, откройте каталог поисковых инструментов. Возможности поиска в каталоге данных описаны на странице платформы веб-данных, а также на страницах Bing, DuckDuckGo, Google News и Google Shopping. Чтобы выполнить вызов в один клик в консоли, откройте Infra Marketplace.
Если вы переходите с Serper, измените эти пункты в указанном порядке. Последняя строка ничего не меняет, а проверяет вашу обработку ошибок.
| Шаг | Serper | EveryInfra |
|---|---|---|
| 1. URL | https://google.serper.dev/<type> | https://api.everyinfra.com/api/v1/search |
| 2. Заголовок | X-API-KEY | Authorization: Bearer |
| 3. Тип результата | Сегмент URL | Поле tool в теле запроса |
| 4. Страна | gl | location |
| 5. Язык, исправление опечаток | hl, autocorrect | Уберите их или используйте web/search с language |
| 6. Временной диапазон | tbs | after, before |
| 7. Ссылка на результат | organic[].link | results[].url |
| 8. Проверка обработки ошибок | — | Передайте один неверный параметр и убедитесь, что ваш код считывает поля allowed и did_you_mean |
Чтобы получить более полное представление, см. страницы «Альтернативы» и «Почему EveryInfra».
Источники
- Главная страница Serper (тарифы, FAQ, пример ответа), Serper, дата обращения: 2026-11-05
- Создать аккаунт, Serper, дата обращения: 2026-11-05
- Войти в аккаунт, Serper, дата обращения: 2026-11-05
- API-ключи, Serper, дата обращения: 2026-11-05 (без входа открывается форма входа)
- Песочница, Serper, скрипт страницы, дата обращения: 2026-11-05
- Условия использования, Serper, обновлено 2024-05-29, дата обращения: 2026-11-05
- Политика конфиденциальности, Serper, пересмотрено 2025-11-05, дата обращения: 2026-11-05
- Поддерживаемые регионы, Serper, дата обращения: 2026-11-05
- Организация Serper-API на GitHub, GitHub, дата обращения: 2026-11-05
- Индекс веб-архива serper.dev, Internet Archive, дата обращения: 2026-11-05
- «postman-code-generators», Postman, дата обращения: 2026-11-05
- «Serper.dev authentication issues», сообщество n8n, 2025-07-26
- «Unauthorized Error (403) when Using SERPER_API_KEY #633», CrewAI, 2024-05-17
- «configure the serper api key? #914», h2oGPT, 2023-10-01
- «Add Serper.dev web search provider plugin #68615», Hermes Agent, 2026-07-21
- «Research: read a spent plan or refused key as what it is #339», GitHub, 2026-10-23
- «Live checks with real keys before release #12», GitHub, 2026-10-22
- «Google Serper Search (SerperDevTool)», CrewAI, дата обращения: 2026-11-05
- «serper_dev_tool.py», CrewAI, дата обращения: 2026-11-05
- «CrewAI 1.15.35», CrewAI, 2026-11-03
- «GoogleSerperAPIWrapper», LangChain, дата обращения: 2026-11-05
- «google_serper.py», LangChain, дата обращения: 2026-11-05
- «SerperDevWebSearch», deepset, дата обращения: 2026-11-05
- «Haystack serperdev websearch.py», deepset, дата обращения: 2026-11-05
- «Serper Search», LiteLLM, дата обращения: 2026-11-05
- «Serper bundle», Langflow, дата обращения: 2026-11-05
- «HTTP Request node», n8n, дата обращения: 2026-11-05
- «HTTP Request credentials», n8n, дата обращения: 2026-11-05
- «MCP Client Tool node», n8n, дата обращения: 2026-11-05
- «n8n 2.46.6», n8n, 2026-11-04
- «mcp-server-serper», GitHub, дата обращения: 2026-11-05
- «serper-mcp-server», GitHub, дата обращения: 2026-11-05
- «Model Context Protocol Specification 2026-07-28», MCP, дата обращения: 2026-11-05
- «MCP Authorization», MCP, дата обращения: 2026-11-05
- «Connect Claude Code to tools via MCP», Anthropic, дата обращения: 2026-11-05
- «RFC 9110: HTTP Semantics», IETF, 2022-06
- «RFC 6585: Additional HTTP Status Codes», IETF, 2012-04
- «RFC 9457: Problem Details for HTTP APIs», IETF, 2023-07
- «422 Unprocessable Content», MDN, дата обращения: 2026-11-05
- «Retry-After», MDN, дата обращения: 2026-11-05
- «Supported secret scanning patterns», GitHub, дата обращения: 2026-11-05
- «Secret scanning blocks Anthropic keys by default, adds Salesforce», GitHub, 2026-10-13
- «Push protection beyond predefined secret patterns», GitHub, 2026-10-28
- «Defining custom patterns for secret scanning», GitHub, дата обращения: 2026-11-05
- «TruffleHog v3.99.8», Truffle Security, 2026-11-02
- «Gitleaks», Gitleaks, дата обращения: 2026-11-05
- «The attack chain behind the v1.107.0 LiteLLM release», LiteLLM, 2026-10-23
- «Security Disclosure: Wednesday October 21st», Railway, 2026-10-21
- «How to Retrieve Your API Key from Serper.dev Dashboard», сообщество Clay, 2025-05-10
- «Secrets Management Cheat Sheet», OWASP, дата обращения: 2026-11-05
- «The Twelve-Factor App: Config», 12factor.net, дата обращения: 2026-11-05
- «python-dotenv», PyPI, дата обращения: 2026-11-05
- «Requests Quickstart», Requests, дата обращения: 2026-11-05
- Каталог поисковых инструментов EveryInfra, EveryInfra, дата обращения: 2026-11-05 00:16 SGT
- Каталог возможностей сбора данных EveryInfra, EveryInfra, дата обращения: 2026-11-05 00:16 SGT
- Спецификация OpenAPI EveryInfra, EveryInfra, дата обращения: 2026-11-05
Справка BL-92