ツールを実行する

実行は、入力をツールに送り、最大費用を残高から仮押さえし、結果を 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 には終了までに返された結果が入ります。支払いはその結果分だけです。

各アイテムはツール独自の形式による 1 件の結果です。フィールド名はツールごとに異なります。

長い実行をポーリングする#

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"
}

status が running でなくなるまで GET /v1/tools/runs/{run_id} を呼び出します。?wait=60 を付けると、各リクエストはすぐに返らず、サーバー側で最大 60 秒待ちます。ポーリングの間に sleep を入れる必要はありません。

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

レスポンスの形式とステータスコードは実行リクエストと同じです。進行中は 202、終了すると items 付きの 200 が返ります。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)"'

結果をページ送りで読む#

デフォルトでは、終了した実行はすべての結果を一度に返します。大きな実行の場合や結果を再取得する場合は、GET /v1/tools/runs/{run_id} に offset と limit を指定して、ページ単位で読み込みます。

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 です。

結果の再取得は無料です。課金は実行の精算時に 1 回だけです。

結果を一時的に読み込めない場合、レスポンスは "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 のリストなど、入力リストの各項目につき 1 件の結果を返すツールでは、デフォルトはそのリストの長さです。
• 最小実行サイズ。 一部のツールは最小サイズ以上のバッチでしか実行できません。それより少ない件数を指定すると、上限はその最小値まで引き上げられます。これらのツールの default_results には、すでにこの最小値が反映されています。

ツールに独自の件数フィールド（maxResults や maxReviewsPerCompany など）がある場合、max_results はそのフィールドにも上限として適用されるため、両方を設定する必要はありません。件数フィールドをより小さい値にすると返る結果は少なくなることがありますが、仮押さえは引き続き 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 キー自体の利用上限を超えてしまう場合、実行には This run can cost up to $…, which would take this API key past its spend limit. というメッセージ付きの 402 が返ります。

エラー#

エラーは API の他の部分と同じ形式で、type と読みやすい message を持つ error オブジェクトです。エラーを返したリクエストには何も課金されません。

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 で追跡します。ブラウザエージェントを参照してください。