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

Запуск передаёт ваши входные данные инструменту, резервирует максимальную стоимость на балансе и возвращает результаты в JSON. Большинство запусков завершается за 5–60 секунд. Вам понадобятся API-ключ и баланс, достаточный для покрытия максимальной стоимости запуска.

Запуск#

Отправьте входные данные инструмента и лимит результатов на POST /v1/tools/{id}/run:

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",
      "language": "en"
    },
    "max_results": 20
  }'

Запрос ждёт завершения запуска. Что вернётся, зависит от того, успел ли он завершиться за wait секунд:

Чтение результата#

Запуск, успевший завершиться, возвращает 200:

{
  "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",
      "categories": ["Coffee shop"],
      "formattedAddress": "9817 Anderson Mill Rd, Austin, TX 78750",
      "website": "https://www.godsentcoffee.com/",
      "rating": 5,
      "reviewCount": 237,
      "placeId": "ChIJq7RZDGczW4YRyCS5Z0KiiDE",
      "googleMapsUri": "https://www.google.com/maps/search/?api=1&query=Godsent%20Coffee&query_place_id=ChIJq7RZDGczW4YRyCS5Z0KiiDE"
    }
  ],
  "offset": 0,
  "next_offset": null
}

200 означает, что запуск завершился, но не обязательно успешно. Проверьте status:

• succeeded: запуск выполнен. items содержит до max_results результатов.
• failed, timed_out или stopped: запуск завершился досрочно. error объясняет причину, а items содержит всё, что он успел выдать. Вы платите только за эти результаты.

Каждый элемент — один результат в собственном формате инструмента. Названия полей у разных инструментов различаются.

Опрос долгого запуска#

Запуск, который продолжается дольше wait секунд, возвращается с кодом 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}, пока status не перестанет быть running. Передавайте ?wait=60, чтобы каждый запрос ждал на сервере до 60 секунд, а не возвращался сразу. Делать паузы между опросами не нужно.

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

Ответ имеет ту же структуру и те же коды статуса, что и запрос на запуск: 202, пока запуск идёт, и 200 с items после завершения. До завершения results остаётся равным 0.

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

Полный пример#

Запустите инструмент, опрашивайте его до завершения, затем выведите результаты. Сначала задайте LOVELY_API_KEY.

# Requires jq.
RUN=$(curl -s 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}')
ID=$(echo "$RUN" | jq -r .id)

while [ "$(echo "$RUN" | jq -r .status)" = "running" ]; do
  RUN=$(curl -s "https://lovelyrouter.com/v1/tools/runs/$ID?wait=60" \
    -H "Authorization: Bearer $LOVELY_API_KEY")
done

echo "$RUN" | jq '{status, results, charge_usd, error}'
echo "$RUN" | jq -r '.items[]? | "\(.title)  \(.rating)"'

Постраничное чтение результатов#

По умолчанию завершённый запуск возвращает все результаты сразу. Для больших запусков или чтобы получить результаты повторно, читайте их постранично через offset и limit в GET /v1/tools/runs/{run_id}:

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

• offset — индекс первого возвращаемого результата. По умолчанию 0.
• limit — размер страницы, от 1 до max_results запуска; это же значение используется по умолчанию.
• Ответ повторяет offset и задаёт в next_offset смещение следующей страницы или null на последней странице.

Повторное чтение результатов бесплатно. Оплата списывается один раз — при расчёте запуска.

Если результаты временно не удаётся загрузить, в ответе будут "items": null и сообщение items_error. На сам запуск и списание это не влияет. Запросите ту же страницу ещё раз.

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

Остановите ненужный запуск через POST /v1/tools/runs/{run_id}/stop:

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

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

Обычно остановка занимает несколько секунд. Если запуск не завершился примерно за 10 секунд, ответ будет 202, и вы опрашиваете его как обычно.

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

Каждый ответ о запуске — это объект запуска. Чаще всего вам понадобятся поля:

Все поля перечислены в разделе Объект запуска справочника API.

Оплата#

При старте запуска на балансе резервируется его максимальная стоимость: плата за вызов плюс плата за результат, умноженная на max_results. Пока запуск идёт, резерв отображается в reserved_usd. Когда запуск завершается, списывается плата за то, что он вернул, заполняется charge_usd, а остаток резерва возвращается на баланс.

Списание никогда не превышает резерв. Расходы на инструменты учитываются в балансе и лимите расходов ключа так же, как расходы на модели, а каждый запуск со списанием виден в разделе Инструменты панели управления. Общие сведения о ценах — в разделе Инструменты данных.

Как определяется max_results#

Лимит, который фактически использует запуск, указан в поле max_results объекта запуска, и резерв рассчитывается от него:

• Вы задали значение. Используется ваше значение; если оно больше max_results инструмента, оно понижается до него.
• Вы не указали значение. Применяется default_results инструмента. Для инструментов, которые возвращают по одному результату на каждый элемент входного списка (например, списка имён профилей или URL), значение по умолчанию равно длине этого списка.
• Минимальный размер запуска. Некоторые инструменты работают только пакетами не меньше определённого размера. Если вы запросите меньше, лимит поднимается до этого минимума. default_results таких инструментов уже это учитывает.

max_results также ограничивает собственное поле количества инструмента, если оно есть (например, maxResults или maxReviewsPerCompany), поэтому задавать оба не нужно. Если поле количества меньше, запуск может вернуть меньше результатов, но резерв всё равно рассчитывается от max_results. Входной список длиннее max_results обрезается до max_results элементов.

Недостаточно средств#

Если баланса не хватает на резерв, запуск отклоняется с кодом 402:

{
  "error": {
    "type": "insufficient_quota",
    "message": "Insufficient balance: this run can cost up to $0.04835 (200 places). Lower max_results or top up."
  }
}

Уменьшите max_results или пополните баланс. Если резерв превысит собственный лимит расходов API-ключа, запуск получит 402 с сообщением This run can cost up to $…, which would take this API key past its spend limit.

Ошибки#

Ошибки имеют ту же структуру, что и в остальном API: объект error с полем type и понятным сообщением message. За запрос, вернувший ошибку, ничего не списывается.

Как устроены ошибки во всём API, см. в разделе Ошибки.

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

GET /v1/tools/runs возвращает запуски вашей учётной записи, начиная с новых, без их элементов:

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

limit — от 1 до 100 (по умолчанию 20). Если запусков больше, поле next в ответе содержит курсор: передайте его как ?before=, чтобы получить следующую страницу. Когда next равно null, вы получили все запуски.

Запуск браузерного агента#

Браузерный агент есть в каталоге как browser-agent, поэтому его тоже запускает POST /v1/tools/browser-agent/run. Передайте в input его goal и start_url, а в max_results — максимальное число шагов. Запрос возвращает 202 и браузерный запуск, за которым вы следите через API браузера. См. Браузерный агент.