Lovely Router文档
获取密钥
数据工具

运行工具

启动运行，一次调用拿到结果或轮询获取，分页读取大量结果，提前停止运行，并准确了解每次运行的费用。

一次运行会把你的输入发给工具，从你的余额中预留它的最高费用，并以 JSON 返回结果。大多数运行在 5 到 60 秒内完成。你需要一个 API 密钥，以及足以支付本次运行最高费用的余额。

启动运行#

把工具的输入和结果上限发送到 POST /v1/tools/{id}/run：

cURL
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
  }'

请求体参数

inputobject默认 {}

工具的输入，须符合 GET /v1/tools/{id} 返回的 input_schema。input_schema.required 中的字段必须设置。序列化为 JSON 后最多 50,000 个字符。

max_resultsinteger

本次运行最多返回并计费的结果数。默认为工具的 default_results。超过工具 max_results 的值会被降到该值。参阅上限如何确定。

waitinteger默认 60

返回响应前等待运行完成的秒数，范围 0 到 300。也可以通过查询参数 ?wait= 传入。

请求会等待运行。返回什么取决于运行是否在 wait 秒内完成：

状态码含义
200运行已结束。响应体包含最终的 status、扣费以及 items 中的结果。
202运行仍在进行。响应体包含它的 id 和一个 poll 路径。轮询它。
4xx、5xx运行没有启动，不产生任何扣费。参阅错误。

读取结果#

在等待时间内结束的运行返回 200：

JSON
{
  "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 中是它在结束前返回的结果。你只为这些结果付费。

每个 item 是一条结果，格式由工具自己决定。不同工具的字段名各不相同。

轮询长时间运行#

wait 秒后仍在进行的运行返回 202：

JSON
{
  "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 秒，而不是立即返回。两次轮询之间无需 sleep。

cURL
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
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，默认也是 max_results。
  • 响应会原样带回 offset，并把 next_offset 设为下一页的偏移量；最后一页则为 null。

再次读取结果是免费的。费用只在运行结算时收取一次。

如果结果暂时无法加载，响应中会出现 "items": null 和一条 items_error 消息。运行本身及其扣费不受影响。重新请求同一页即可。

停止运行#

用 POST /v1/tools/runs/{run_id}/stop 停止不再需要的运行：

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

运行以 stopped 状态结束。你只需为停止前已返回的结果支付每条结果费，不收每次调用费。响应是已结算的运行，这些结果在 items 中。停止一个已经结束的运行，会原样返回该运行。

停止通常需要几秒钟。如果运行在大约 10 秒内仍未收尾，响应为 202，照常轮询即可。

运行对象#

每个运行相关的响应都是一个运行对象。最常用的字段：

字段含义
id运行 ID，由 run_ 加 24 个字符组成。用它来轮询或停止运行。
statusrunning、succeeded、failed、timed_out 或 stopped
results已返回并计费的结果数。运行结束前为 0。
max_results本次运行适用的结果上限
charge_usd本次运行的费用。结算前为 null。
reserved_usd运行结算前在你余额上的预留金额。结算后为 0。
error运行提前结束的原因，或 null

所有字段见 API 参考中的运行对象。

计费#

启动运行时，会从你的余额中预留它的最高费用：每次调用费加上每条结果费乘以 max_results。运行进行期间，这笔预留显示为 reserved_usd。运行结束时，按返回的结果扣费，设置 charge_usd，预留的剩余部分退回你的余额。

结果扣费
succeeded每次调用费 + 每条结果费 × results
failed、timed_out每条结果费 × 结束前已返回的结果数
stopped每条结果费 × 你停止前已返回的结果数
启动时被拒绝（任何 4xx 或 5xx）不收费，也不保留预留。

扣费永远不会超过预留。与模型消费一样，工具消费计入你的余额和密钥的消费上限，每次运行及其扣费都会列在控制台的工具页面中。计费的总体说明请参阅数据工具。

max_results 如何确定#

运行实际使用的上限就是运行对象中的 max_results，预留金额也以它为准：

  • 你设置了它。 使用你的值；如果高于工具的 max_results，则降到该值。
  • 你没有设置。 使用工具的 default_results。对于按输入列表中每个条目返回一条结果的工具（例如一组账号名或 URL），默认值就是该列表的长度。
  • 最小运行规模。 少数工具只能按一定的最小批量运行。如果你要求的数量更少，上限会被提高到该最小值。这些工具的 default_results 已经考虑了这一点。

如果工具有自带的数量字段（例如 maxResults 或 maxReviewsPerCompany），max_results 也会限制它，因此你不需要两个都设置。如果你把数量字段设得更低，运行返回的结果可能更少，但预留仍以 max_results 为准。长度超过 max_results 的输入列表会被截断为 max_results 个条目。

余额不足#

如果你的余额不足以支付预留，运行会被拒绝并返回 402：

JSON
{
  "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。返回错误的请求不产生任何扣费。

状态码type原因处理方式
400invalid_request_error请求体不是 JSON、input 不是对象、缺少必填的输入字段，或工具拒绝了该输入对照工具的 input_schema 检查 input。错误消息会指出缺少的字段。
401authentication_errorAPI 密钥缺失、无效、已吊销或已过期在 Authorization: Bearer 中发送有效的密钥。
402insufficient_quota余额或密钥的消费上限不足以支付预留调低 max_results 或充值。
404not_found工具 id 不存在，或运行 id 不存在或属于其他账户检查 id。用 POST /v1/tools/discover 查找工具。
413invalid_request_errorinput 超过 50,000 个字符减少每次运行的输入。
429rate_limit_exceeded你的账户已有 10 个运行在进行中等其中一个结束后重试。
502tool_unavailable工具无法启动稍后重试。

整个 API 的错误机制请参阅错误。

列出你的运行#

GET /v1/tools/runs 按从新到旧的顺序返回你账户的运行，不含 items：

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

limit 范围为 1 到 100（默认 20）。如果还有更多运行，响应中的 next 是一个游标：把它作为 ?before= 传入即可获取下一页。next 为 null 时，说明已经全部获取。

运行浏览器智能体#

浏览器智能体在目录中的 id 是 browser-agent，因此 POST /v1/tools/browser-agent/run 也能启动它。把它的 goal 和 start_url 放进 input，并把 max_results 设为最大步数。它返回 202 和一个浏览器运行，之后用浏览器 API 跟进。参阅浏览器智能体。

← 上一页
找到合适的工具
数据工具
下一页 →
MCP 服务器
数据工具