Lovely Routerドキュメント
キーを取得
API リファレンス

ツールのエンドポイント

/v1/tools のすべてのエンドポイントと、ツールオブジェクト、実行オブジェクトのリファレンスです。

ツール API では、データツールの一覧取得、検索、実行ができます。リクエストとレスポンスは JSON です。ベース URL は https://lovelyrouter.com/v1 です。

認証。 カタログのエンドポイント（一覧、取得、検索、プラン）は公開されています。ツールの実行と、実行の読み取りには、Authorization: Bearer ヘッダーで API キーを送る必要があります。ツールの実行は、モデルと同じプリペイド残高から課金されます。

エラー。 失敗したリクエストは、type と message を持つ error オブジェクトを返します。エラーを参照してください。

言語。 カタログのエンドポイントは 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

実行の input の JSON Schema。取得時のみ含まれます。

example_inputobject

そのまま使える入力。取得時のみ含まれます。

timeout_sinteger

実行の制限時間（秒）。これを超えた実行は timed_out で終了します。取得時のみ含まれます。

runobject

そのまま使える実行リクエスト。method、path、入力例とデフォルトの上限を含む body で構成されます。取得時のみ含まれます。

The tool object
{
  "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 にツールを含むリストオブジェクトを返します。

curl "https://lovelyrouter.com/v1/tools?category=reviews"
Response
{
  "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}

1 つのツールを、input_schema、example_input、timeout_s、そのまま使える run リクエストとともに返します。キーは不要です。不明な ID には 404 を返します。

パスパラメータ

idstring必須

ツール ID。

クエリパラメータ

langstringデフォルト en

zh または ja を指定すると、名前と説明がローカライズされます。入力スキーマは英語のままです。

cURL
curl https://lovelyrouter.com/v1/tools/trustpilot-reviews
Response
{
  "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 を返します。results は score 付きのツールオブジェクトです。スコアは同じクエリ内のツール同士を比べる目的にしか使えません。query のないボディには 400 を返します。

cURL
curl https://lovelyrouter.com/v1/tools/discover \
  -H "content-type: application/json" \
  -d '{"query": "google maps reviews", "limit": 2}'
Response
{
  "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

タスクを平易な言葉で説明すると、順序付きのプランが返ります。プランには、最初に実行するツール、必要に応じて 2 つ目のツール、近い代替ツールが含まれ、それぞれに入力例と見積もり費用が付きます。無料で、レート制限は API キーごとに 1 分あたり 100 リクエストです。キーなしの呼び出し元は、1 分あたり 100 リクエストの枠を共有します。制限を超えると、retry-after ヘッダー付きで 429 を返します。

ボディパラメータ

taskstring必須

タスク。最大 2,000 文字です。これより長いタスクには 413 を返します。

limitintegerデフォルト 5

返す提案の最大数。1〜8。

langstringデフォルト en

zh または ja を指定すると、名前と説明がローカライズされます。

戻り値

taskstring

送信したタスク。

sourcestring

プランナーによるプランの場合は ai、プランナーが利用できずキーワード一致で返した場合は keyword。

cachedboolean

同一タスクのキャッシュ（1 日保持）から返されたプランかどうか。

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"}'
Response
{
  "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
}

実行オブジェクト#

ツールの 1 回の実行です。実行、取得、停止、一覧の各エンドポイントが返します。

属性

idstring

実行 ID。run_ に続く 24 文字です。

objectstring

常に tool_run。

toolstring

ツール ID。

tool_namestring

ツールの表示名。

statusstring

running、succeeded、failed、timed_out（ツールの制限時間に到達）、stopped（あなたが停止）のいずれか。

inputobject or null

この実行が使った入力。ツールの旧バージョンのフィールド名は現在の名前に置き換えられ、ツールの件数フィールドには結果の上限が入ります（件数が検索ごとに数えられるツールでは、上限を各検索に均等に割り振ります）。接続が切れた後などに、実行とクエリを対応付けるのに使えます。2026 年 10 月 20 日より前の一部の実行では null。

resultsinteger

返され、課金された結果の数。実行が終わるまでは 0。

max_resultsinteger

この実行に適用される結果数の上限。指定した値と異なる場合があります。ツールの最大値まで引き下げられるか、ツールの最小実行サイズまで引き上げられるためです。

charge_usdnumber or null

実行にかかった費用。精算されるまでは null。

reserved_usdnumber

実行が未精算の間、残高から仮押さえされている金額。精算後は 0。

errorstring or null

実行が途中で終了した理由。running と succeeded の実行では null。

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）が入ります。

The run object
{
  "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 キーが必要です。

終了した実行オブジェクトとその items を 200 で返すか、実行中の実行と poll パスを 202 で返します。200 でも failed や timed_out の実行が返ることがあるため、status を確認してください。エラーステータスが返った場合、実行は開始されておらず、何も課金されていません。

ツール ID はボディで送ることもできます。"tool": "google-maps-places" を付けて POST /v1/tools/run を呼び出します。

browser-agent を実行した場合は、代わりに 202 とブラウザ実行が返り、max_results は最大ステップ数として扱われます。ブラウザエージェントを参照してください。

パスパラメータ

idstring必須

ツール ID。

ボディパラメータ

inputobjectデフォルト {}

ツールへの入力。input_schema に従います。input_schema.required のフィールドは必須です。JSON で最大 50,000 文字。

max_resultsinteger

返して課金する結果数の上限。ツールの max_results まで指定できます。デフォルトはツールの default_results です。ただし、エントリのリストを受け取り、エントリごとに 1 件の結果を返すツールでは、リストの長さになります。

waitintegerデフォルト 60

実行の終了を待つ秒数。0〜300。?wait= クエリパラメータでも指定できます。

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
  }'
Response (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 まで指定でき、デフォルトも max_results です。

cURL
curl "https://lovelyrouter.com/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60&offset=0&limit=50" \
  -H "Authorization: Bearer $LOVELY_API_KEY"
Response
{
  "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 で終了し、停止前に返された結果分の結果単価だけを支払います。呼び出し料金はかかりません。それらの結果を含む精算済みの実行を返します。約 10 秒経っても終了処理が続いている場合は 202 を返します。終了済みの実行を停止した場合は、その実行を変更せずに返します。

パスパラメータ

run_idstring必須

実行 ID。

cURL
curl -X POST https://lovelyrouter.com/v1/tools/runs/run_8c1f0e2a9b7d4f3e6a5c2b1d/stop \
  -H "Authorization: Bearer $LOVELY_API_KEY"
Response
{
  "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 を返します。next は次のページのカーソルで、それ以上実行がない場合は null です。

cURL
curl "https://lovelyrouter.com/v1/tools/runs?limit=2" \
  -H "Authorization: Bearer $LOVELY_API_KEY"
Response
{
  "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原因
400invalid_request_errorボディが JSON でない、input がオブジェクトでない、必須の入力フィールドがない、ツールが入力を拒否した、または query / task がない
401authentication_errorAPI キーがない、無効、失効済み、または期限切れ
402insufficient_quota残高またはキーの利用上限で、実行の仮押さえを賄えない
404not_found不明なツール ID、またはその ID の実行がアカウントに存在しない
413invalid_request_errorinput が 50,000 文字を超えている、または task が 2,000 文字を超えている
429rate_limit_exceededアカウントですでに 10 件の実行が進行中、またはプランナーのレート制限に到達
500api_error予期しないエラー。再試行してください。
502tool_unavailableツールを開始できませんでした。課金はされていません。しばらくしてから再試行してください。

エラーが返った実行リクエストは課金されません。API 全体のエラーについてはエラーを参照してください。

Error
{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required input: companyUrls. See GET /v1/tools/trustpilot-reviews."
  }
}
← 前へ
モデルのエンドポイント
API リファレンス
次へ →
ブラウザのエンドポイント
API リファレンス