Справочник API

Эндпоинты инструментов

Справочник по всем эндпоинтам /v1/tools, объекту инструмента и объекту запуска.

API инструментов позволяет просматривать, искать и запускать инструменты для данных. Запросы и ответы передаются в JSON. Базовый URL — https://lovelyrouter.com/v1.

Аутентификация. Эндпоинты каталога (список, получение, поиск и планирование) публичны. Для запуска инструментов и чтения запусков нужен API-ключ в заголовке Authorization: Bearer. Запуски инструментов оплачиваются с того же предоплаченного баланса, что и модели.

Ошибки. Неудачные запросы возвращают объект error с полями type и message. См. Ошибки.

Языки. Эндпоинты каталога принимают lang (zh или ja) для локализации названий и описаний инструментов — как параметр запроса в GET или как поле тела в POST.

cURL

curl https://lovelyrouter.com/v1/tools/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Объект инструмента#

Инструмент в каталоге. Эндпоинты списка и поиска возвращают сводные поля. Получение инструмента добавляет схему входных данных, пример входных данных, ограничение по времени и готовый запрос на запуск.

Атрибуты

idstring

Id инструмента, используется в путях запуска. Например, google-maps-places.

namestring

Отображаемое название, локализуется через lang.

platformstring

Сайт или источник, из которого инструмент читает данные, например Google Maps или TikTok.

categorystring

Одно из значений: social-media, search, ecommerce, lead-generation, reviews, jobs, travel, web.

descriptionstring

Что возвращает инструмент, локализуется через lang.

priceobject

Актуальная цена.

default_resultsinteger

Предел числа результатов, который используется, если вы не задали max_results.

max_resultsinteger

Наибольший предел числа результатов, который принимает запуск этого инструмента.

featuredboolean

Отмечен ли инструмент как популярный на странице инструментов.

input_schemaobject

JSON Schema для input запуска. Только при получении инструмента.

example_inputobject

Входные данные, которые работают как есть. Только при получении инструмента.

timeout_sinteger

Ограничение времени запуска в секундах. Запуск, превысивший его, завершается как timed_out. Только при получении инструмента.

runobject

Готовый запрос на запуск: method, path и body с примером входных данных и пределом по умолчанию. Только при получении инструмента.

Объект инструмента

{
  "id": "google-maps-places",
  "name": "Search Google Maps places",
  "platform": "Google Maps",
  "category": "search",
  "description": "Find local businesses on Google Maps by keyword and location: name, address, phone, website, rating, review count, opening hours, coordinates.",
  "price": {
    "per_call_usd": 0.00075,
    "per_result_usd": 0.000238,
    "unit": "place",
    "label": "$0.000238 / place + $0.00075 / call"
  },
  "default_results": 10,
  "max_results": 200,
  "featured": true
}

Список инструментов#

GET/v1/tools

Возвращает все доступные инструменты. Ключ не нужен.

Параметры запроса

categorystring

Только инструменты этой категории, например reviews.

qstring

Ключевые слова. Возвращает подходящие инструменты, упорядоченные по релевантности, до 100.

langstringПо умолчанию en

zh или ja для локализации названий и описаний.

Возвращает объект списка с инструментами в data.

Shell

curl "https://lovelyrouter.com/v1/tools?category=reviews"

Ответ

{
  "object": "list",
  "data": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "description": "Reviews of a Google Maps place (by place ID or URL): text, stars, date, owner replies.",
      "price": {
        "per_call_usd": 0,
        "per_result_usd": 0.000675,
        "unit": "review",
        "label": "$0.000675 / review"
      },
      "default_results": 20,
      "max_results": 500,
      "featured": false
    }
  ]
}

Получение инструмента#

GET/v1/tools/{id}

Возвращает один инструмент с его input_schema, example_input, timeout_s и готовым запросом run. Ключ не нужен. Для неизвестного id возвращает 404.

Параметры пути

idstringОбязательно

Id инструмента.

Параметры запроса

langstringПо умолчанию en

zh или ja для локализации названия и описания. Схемы входных данных остаются на английском.

cURL

curl https://lovelyrouter.com/v1/tools/trustpilot-reviews

Ответ

{
  "id": "trustpilot-reviews",
  "name": "Trustpilot reviews",
  "platform": "Trustpilot",
  "category": "reviews",
  "description": "Trustpilot reviews of a company by domain: stars, text, date, reply.",
  "price": {
    "per_call_usd": 0.0075,
    "per_result_usd": 0.0015,
    "unit": "review",
    "label": "$0.0015 / review + $0.0075 / call"
  },
  "default_results": 20,
  "max_results": 500,
  "featured": false,
  "input_schema": {
    "type": "object",
    "properties": {
      "companyUrls": {
        "type": "array",
        "title": "Company URLs or Domains",
        "description": "Enter Trustpilot company URLs (e.g., https://www.trustpilot.com/review/example.com) or just the domain (e.g., example.com). One per line."
      },
      "maxReviewsPerCompany": {
        "type": "integer",
        "title": "Max reviews per company (reviews)",
        "default": 0,
        "minimum": 0
      }
    },
    "required": ["companyUrls"]
  },
  "example_input": {
    "companyUrls": ["pipedrive.com"],
    "maxReviewsPerCompany": 20
  },
  "timeout_s": 300,
  "run": {
    "method": "POST",
    "path": "/v1/tools/trustpilot-reviews/run",
    "body": {
      "input": { "companyUrls": ["pipedrive.com"], "maxReviewsPerCompany": 20 },
      "max_results": 20
    }
  }
}

Поиск инструментов#

POST/v1/tools/discover

Поиск по каталогу по ключевым словам. Возвращает лучшие совпадения, каждое с оценкой релевантности score. Ключ не нужен.

Параметры тела запроса

querystringОбязательно

Что вам нужно, в нескольких словах. Например, tiktok comments. Используются первые 1 000 символов.

limitintegerПо умолчанию 5

Число результатов, от 1 до 40.

langstringПо умолчанию en

zh или ja для локализации названий и описаний.

Возвращает query, count и results: объекты инструментов с полем score. Оценки позволяют сравнивать инструменты только в рамках одного запроса. Тело без query возвращает 400.

cURL

curl https://lovelyrouter.com/v1/tools/discover \
  -H "content-type: application/json" \
  -d '{"query": "google maps reviews", "limit": 2}'

Ответ

{
  "query": "google maps reviews",
  "count": 2,
  "results": [
    {
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "description": "Reviews of a Google Maps place (by place ID or URL): text, stars, date, owner replies.",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "default_results": 20,
      "max_results": 500,
      "featured": false,
      "score": 0.889
    },
    {
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "platform": "Google Maps",
      "category": "search",
      "description": "Find local businesses on Google Maps by keyword and location: name, address, phone, website, rating, review count, opening hours, coordinates.",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "default_results": 10,
      "max_results": 200,
      "featured": true,
      "score": 0.717
    }
  ]
}

Планирование задачи#

POST/v1/tools/suggest

Опишите задачу простыми словами и получите упорядоченный план: инструмент, который нужно запустить первым, необязательный второй инструмент и близкие альтернативы — каждый с примером входных данных и оценкой стоимости. Бесплатно, с лимитом 100 запросов в минуту на API-ключ. Вызовы без ключа делят общий пул в 100 запросов в минуту. При превышении лимита эндпоинт возвращает 429 с заголовком retry-after.

Параметры тела запроса

taskstringОбязательно

Задача, до 2 000 символов. Более длинные задачи возвращают 413.

limitintegerПо умолчанию 5

Максимальное число предложений, от 1 до 8.

langstringПо умолчанию en

zh или ja для локализации названий и описаний.

Возвращает

taskstring

Отправленная вами задача.

sourcestring

ai — план от планировщика, keyword — совпадения по ключевым словам, когда планировщик недоступен.

cachedboolean

Взят ли план из кеша идентичных задач (хранится сутки).

countinteger

Число предложений. 0, если ни один инструмент не подходит для задачи.

suggestionsarray

План по порядку. Каждая запись — объект инструмента плюс:

total_est_cost_usdnumber

Сумма шагов primary и next. Альтернативы не учитываются.

cURL

curl https://lovelyrouter.com/v1/tools/suggest \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"task": "Find vegan restaurants in Austin and summarize what their reviews complain about"}'

Ответ

{
  "task": "Find vegan restaurants in Austin and summarize what their reviews complain about",
  "source": "ai",
  "cached": false,
  "count": 2,
  "suggestions": [
    {
      "step": 1,
      "role": "primary",
      "match": 0.961,
      "id": "google-maps-places",
      "name": "Search Google Maps places",
      "platform": "Google Maps",
      "category": "search",
      "price": { "per_call_usd": 0.00075, "per_result_usd": 0.000238, "unit": "place", "label": "$0.000238 / place + $0.00075 / call" },
      "input": {
        "searchTerms": ["coffee shop"],
        "location": "Austin, Texas, USA",
        "maxResults": 3,
        "language": "en"
      },
      "input_required": [],
      "max_results": 10,
      "est_cost_usd": 0.00313,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-places/run",
        "body": { "input": { "searchTerms": ["coffee shop"], "location": "Austin, Texas, USA", "maxResults": 3, "language": "en" }, "max_results": 10 }
      }
    },
    {
      "step": 2,
      "role": "next",
      "match": 0.875,
      "id": "google-maps-reviews",
      "name": "Google Maps reviews",
      "platform": "Google Maps",
      "category": "reviews",
      "price": { "per_call_usd": 0, "per_result_usd": 0.000675, "unit": "review", "label": "$0.000675 / review" },
      "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" },
      "input_required": [],
      "max_results": 20,
      "est_cost_usd": 0.0135,
      "run": {
        "method": "POST",
        "path": "/v1/tools/google-maps-reviews/run",
        "body": { "input": { "placeIds": ["ChIJN1t_tDeuEmsRUsoyG83frY4"], "maxReviews": 3, "reviewsSort": "newest" }, "max_results": 20 }
      }
    }
  ],
  "total_est_cost_usd": 0.01663
}

Объект запуска#

Запуск инструмента. Возвращается эндпоинтами запуска, получения, остановки и списка.

Атрибуты

idstring

Id запуска: run_ и 24 символа.

objectstring

Всегда tool_run.

toolstring

Id инструмента.

tool_namestring

Отображаемое название инструмента.

statusstring

running, succeeded, failed, timed_out (достигнуто ограничение времени инструмента) или stopped (остановлен вами).

inputobject or null

Входные данные, с которыми выполнялся запуск: имена полей из прежних версий инструмента приведены к текущим, а поле лимита инструмента заполнено из предела числа результатов (с разбивкой по поискам у инструментов, чей лимит считается на каждый поиск). Используйте его, чтобы сопоставлять запуски со своими запросами, например после обрыва соединения. null для некоторых запусков, сделанных до 20 октября 2026 года.

resultsinteger

Число возвращённых и оплаченных результатов. 0, пока запуск не завершён.

max_resultsinteger

Предел числа результатов, действующий для этого запуска. Он может отличаться от запрошенного: понижается до максимума инструмента или повышается до минимального размера запуска инструмента.

charge_usdnumber or null

Сколько стоил запуск. null, пока по запуску не произведён расчёт.

reserved_usdnumber

Сумма, зарезервированная на балансе, пока расчёт по запуску не произведён. После расчёта — 0.

errorstring or null

Почему запуск завершился досрочно. null для запусков в статусах running и succeeded.

created_atstring

Когда запуск начался, в формате ISO 8601.

finished_atstring or null

Когда запуск завершился, в формате ISO 8601. null, пока он выполняется.

pollstring

Путь для опроса результата. Только в ответах 202.

itemsarray or null

Результаты в собственном формате инструмента. Только после завершения запуска и не в списке. null, если результаты временно недоступны; см. items_error.

offsetinteger

Индекс первого результата в items. Только если у запуска есть результаты.

next_offsetinteger or null

Смещение следующей страницы результатов или null на последней странице.

items_errorstring

Присутствует, только когда items равно null. Запросите запуск ещё раз, чтобы загрузить результаты.

reportobject

Сведения обо всём запуске, которые некоторые инструменты возвращают помимо items. Инструменты переходов с сайтов (site-referrals, site-outgoing): запрошенный site, period, число сайтов в списке sites, unattributed (переходы, не отнесённые ни к одному сайту, или null) и для site-referrals — monthly: общее число переходов на сайт по месяцам, например [{"month": "2026-04", "visits": 55133}] (у site-outgoing — null). У каждого их результата тоже есть monthly — посещения этого сайта по месяцам или null, если помесячных данных нет.

Объект запуска

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "succeeded",
  "input": {
    "searchTerms": ["coffee shop"],
    "location": "Austin, Texas, USA",
    "maxResults": 20,
    "language": "en",
    "radius": 20
  },
  "results": 20,
  "max_results": 20,
  "charge_usd": 0.00551,
  "reserved_usd": 0,
  "error": null,
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": "2026-10-11T15:02:38.917Z",
  "items": [
    {
      "title": "Godsent Coffee",
      "categoryName": "Coffee shop",
      "address": "9817 Anderson Mill Rd, Austin, TX 78750",
      "totalScore": 5,
      "reviewsCount": 237,
      "placeId": "ChIJq7RZDGczW4YRyCS5Z0KiiDE"
    }
  ],
  "offset": 0,
  "next_offset": null
}

Запуск инструмента#

POST/v1/tools/{id}/run

Начинает запуск и ждёт его до wait секунд. Максимальная стоимость запуска (плата за вызов плюс плата за результат, умноженная на предел) резервируется на балансе, а расчёт производится по завершении. Нужен API-ключ.

Возвращает 200 с завершённым объектом запуска и его items или 202 с выполняющимся запуском и путём poll. Ответ 200 может содержать запуск в статусе failed или timed_out: проверяйте status. Любой статус ошибки означает, что запуск не начался и ничего не списано.

Id инструмента можно передать и в теле: POST /v1/tools/run с "tool": "google-maps-places".

Запуск browser-agent вместо этого возвращает 202 и запуск браузера, где max_results — максимальное число шагов. См. Браузерный агент.

Параметры пути

idstringОбязательно

Id инструмента.

Параметры тела запроса

inputobjectПо умолчанию {}

Входные данные инструмента в соответствии с его input_schema. Поля из input_schema.required обязательны. До 50 000 символов в виде JSON.

max_resultsinteger

Максимальное число результатов для возврата и оплаты, не больше max_results инструмента. По умолчанию — default_results инструмента, а для инструментов, которые принимают список записей с одним результатом на каждую, — длина списка.

waitintegerПо умолчанию 60

Сколько секунд ждать завершения запуска, от 0 до 300. Также принимается как параметр запроса ?wait=.

Shell

curl https://lovelyrouter.com/v1/tools/google-maps-places/run \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "input": {"searchTerms": ["coffee shop"], "location": "Austin, Texas, USA"},
    "max_results": 20
  }'

Ответ (202)

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "running",
  "results": 0,
  "max_results": 20,
  "charge_usd": null,
  "reserved_usd": 0.00551,
  "error": null,
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": null,
  "poll": "/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60"
}

Получение запуска#

GET/v1/tools/runs/{run_id}

Возвращает запуск, при необходимости дожидаясь его завершения. Опрос завершённого запуска производит по нему расчёт, если тот ещё не был произведён. Возвращает 202, пока запуск выполняется, и 200 после его завершения, с результатами в items. Запуски другого аккаунта возвращают 404.

Для запуска browser-agent возвращается запуск браузера. См. Браузерный агент.

Параметры пути

run_idstringОбязательно

Id запуска.

Параметры запроса

waitintegerПо умолчанию 0

Сколько секунд ждать завершения выполняющегося запуска, от 0 до 300.

offsetintegerПо умолчанию 0

Индекс первого возвращаемого результата.

limitinteger

Число возвращаемых результатов, от 1 до max_results запуска; это же значение используется по умолчанию.

cURL

curl "https://lovelyrouter.com/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60&offset=0&limit=50" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Ответ

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "succeeded",
  "results": 20,
  "max_results": 20,
  "charge_usd": 0.00551,
  "reserved_usd": 0,
  "error": null,
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": "2026-10-11T15:02:38.917Z",
  "items": [
    { "title": "Godsent Coffee", "totalScore": 5, "reviewsCount": 237, "placeId": "ChIJq7RZDGczW4YRyCS5Z0KiiDE" }
  ],
  "offset": 0,
  "next_offset": null
}

Остановка запуска#

POST/v1/tools/runs/{run_id}/stop

Останавливает выполняющийся запуск. Он завершается как stopped, и вы платите за результаты, полученные до остановки, по цене за результат, без платы за вызов. Возвращает запуск с произведённым расчётом и этими результатами или 202, если примерно через 10 секунд он всё ещё завершается. Остановка завершённого запуска возвращает его без изменений.

Параметры пути

run_idstringОбязательно

Id запуска.

cURL

curl -X POST https://lovelyrouter.com/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d/stop \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Ответ

{
  "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
  "object": "tool_run",
  "tool": "google-maps-places",
  "tool_name": "Search Google Maps places",
  "status": "stopped",
  "results": 4,
  "max_results": 20,
  "charge_usd": 0.018,
  "reserved_usd": 0,
  "error": "The run was stopped. You are billed only for results delivered before it stopped.",
  "created_at": "2026-10-11T15:02:11.204Z",
  "finished_at": "2026-10-11T15:02:19.630Z",
  "items": [
    { "title": "Godsent Coffee", "totalScore": 5, "reviewsCount": 237, "placeId": "ChIJq7RZDGczW4YRyCS5Z0KiiDE" }
  ],
  "offset": 0,
  "next_offset": null
}

Список запусков#

GET/v1/tools/runs

Возвращает запуски вашего аккаунта, сначала новые, без их результатов. Включает запуски, начатые любым из ваших ключей.

Параметры запроса

limitintegerПо умолчанию 20

Число запусков, от 1 до 100.

beforeinteger

Курсор: значение next с предыдущей страницы.

Возвращает объект списка с объектами запусков в data и next — курсором следующей страницы или null, если запусков больше нет.

cURL

curl "https://lovelyrouter.com/v1/tools/runs?limit=2" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Ответ

{
  "object": "list",
  "data": [
    {
      "id": "run_8c1f0e2a9b7d4f3e6a5c2b1d",
      "object": "tool_run",
      "tool": "google-maps-places",
      "tool_name": "Search Google Maps places",
      "status": "succeeded",
      "results": 20,
      "max_results": 20,
      "charge_usd": 0.00551,
      "reserved_usd": 0,
      "error": null,
      "created_at": "2026-10-11T15:02:11.204Z",
      "finished_at": "2026-10-11T15:02:38.917Z"
    },
    {
      "id": "run_51d0b9e4c3a2f1e0d9c8b7a6",
      "object": "tool_run",
      "tool": "trustpilot-reviews",
      "tool_name": "Trustpilot reviews",
      "status": "succeeded",
      "results": 20,
      "max_results": 20,
      "charge_usd": 0.0375,
      "reserved_usd": 0,
      "error": null,
      "created_at": "2026-10-11T14:48:03.512Z",
      "finished_at": "2026-10-11T14:48:21.077Z"
    }
  ],
  "next": 1791730083512
}

Ошибки#

Все ошибки имеют одинаковую структуру. type стабилен, и на него можно опираться в ветвлениях кода. message предназначен для людей и может меняться.

Статус	`type`	Причина
`400`	`invalid_request_error`	Тело не является JSON, `input` не является объектом, отсутствует обязательное поле входных данных, инструмент отклонил входные данные или отсутствует `query` / `task`
`401`	`authentication_error`	API-ключ отсутствует, недействителен, отозван или просрочен
`402`	`insufficient_quota`	Баланса или лимита расходов ключа не хватает на резерв для запуска
`404`	`not_found`	Неизвестный id инструмента или в вашем аккаунте нет запуска с таким id
`413`	`invalid_request_error`	`input` длиннее 50 000 символов или `task` длиннее 2 000
`429`	`rate_limit_exceeded`	В вашем аккаунте уже выполняются 10 запусков, или сработал лимит запросов планировщика
`500`	`api_error`	Непредвиденная ошибка. Повторите запрос.
`502`	`tool_unavailable`	Инструмент не удалось запустить. Плата не списана. Повторите попытку чуть позже.

За запрос на запуск, вернувший ошибку, плата не взимается. Об ошибках API в целом см. Ошибки.

Ошибка

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required input: companyUrls. See GET /v1/tools/trustpilot-reviews."
  }
}