Data tools

Data tools return structured data from the web: web search results, any web page as Markdown, Google Maps places, TikTok comments, LinkedIn profiles, Amazon reviews, job listings. You find a tool, send it a JSON input, and get JSON results back. Each run is billed from your prepaid balance: a per-call fee plus a per-result fee, never more than the cap you set.

There is no separate account or subscription. The API key you use for models works for tools, and tool spend counts toward the same balance and key spend limits.

Try it#

The catalog is public. List it without a key:

curl https://lovelyrouter.com/v1/tools

Running a tool needs a key. This run finds up to 20 coffee shops in Austin and costs at most $0.00551:

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

The response holds the run's status, what it cost and the results in items. Run a tool covers long runs, polling and pagination.

What's in the catalog#

Every tool belongs to one category. Filter by its id with GET /v1/tools?category=reviews, or browse them on the tools page.

Tools are added over time. GET /v1/tools and the tools page always show the current list.

How pricing works#

Each tool has two prices, either of which can be zero:

• Per-call fee, charged once for a run that succeeds.
• Per-result fee, charged for each result the run returns. The unit depends on the tool: a place, a review, a page, a profile.

A run costs:

per-call fee + per-result fee × results returned

Some examples at today's prices:

Prices can change. The tools page and GET /v1/tools show the live price of every tool in its price object.

Cap the cost with max_results#

Every run has a result cap, max_results. A run never returns or bills more results than its cap. When you leave it out, the tool's default_results applies, and you can raise it up to the tool's own max_results.

So the most a run can cost is known before it starts: per-call fee + per-result fee × max_results.

Hold, then settle#

1. Hold. When a run starts, its maximum cost is reserved from your balance. If your balance or the key's spend limit can't cover it, the run is refused with 402 and nothing is charged. Lower max_results or top up.
2. Settle. When the run ends, it is charged for what it actually returned, and the rest of the hold goes back to your balance.

A Google Maps search capped at 20 places holds $0.00551. If 14 places come back, you pay $0.004082 and $0.001428 returns to your balance.

Failed and stopped runs#

A failed run that returned no results costs nothing. Every run and its charge appears in Tools in your dashboard.

The life of a run#

1. 1

   Find a tool

   List or search the catalog, or describe your task to the planner. See Find the right tool.

2. 2

   Read its input schema

   GET /v1/tools/{id} returns the tool's input_schema, an example_input and its price.

3. 3

   Start the run

   POST /v1/tools/{id}/run with your input and a max_results cap. The maximum cost is held from your balance.

4. 4

   Wait or poll

   The request waits up to 60 seconds by default. A run that finishes in time comes back with 200 and its results. A longer run comes back with 202, and you poll GET /v1/tools/runs/{run_id} until it finishes.

5. 5

   Settle and read results

   The finished run reports results, charge_usd and the data in items. Runs nobody polls are settled automatically within minutes, so a hold is never stuck.

Browser agent#

The browser agent is in the same catalog under the id browser-agent. Give it a goal and a start URL and it works through the task in a real browser. It is billed per step instead of per result: max_results sets the maximum number of steps. For its full API, including logins, structured output and human approval, see Browser agent.

Limits#

A run over the concurrency limit is refused with 429. Start it again once another run finishes.

Next steps#