Hottub Search API

Search the web and the Hottub Directory from your agent or app for $0.50 per 1,000 searches, and keep what you find. The first 2,500 searches each month are free. Paying never changes the order of results.

Get a key

Prices

Plan	Price	Included	Speed	Monthly limit
Free 2,500 searches a month at no cost. Show “Results from Hottub Search” with a link wherever people see the results.	No cost	2,500 free a month	60 a minute	2,500 searches a month
Developer Pay as you go: the first 2,500 searches each month are free, then $0.50 per 1,000. You set a monthly limit on what you spend.	$0.50 per 1,000, then $0.35 at volume	2,500 free a month	600 a minute	You choose: $10, $50, $100, $500, $1,000 a month (starts at $50)
Scale The same prices with room to grow: $0.50 per 1,000 up to 5 million searches a month and $0.35 per 1,000 after that, with a higher speed limit and spending limit.	$0.50 per 1,000, then $0.35 at volume	2,500 free a month	1,500 a minute	You choose: $1,000, $2,500, $5,000, $10,000, $25,000 a month (starts at $2,500)

Developer and Scale use one price list, by searches in a calendar month (UTC):

Searches this month	Price
1 – 2,500 searches a month	Free
2,501 – 5,000,000 searches a month	$0.50 per 1,000
Above 5,000,000 searches a month	$0.35 per 1,000

One search is one call to /v1 or one hottub_search call over MCP. Checking your use (/v1/usage) is free. Checked answers are coming later and will be priced on their own.

Calling it

Send your key in the Authorization header (or X-API-Key). Everything else is the same as the free API on the agents page.

curl -s 'https://hottub.tech/v1?q=plumber+spokane+wa&limit=5' \
  -H 'Authorization: Bearer hsk_…'

MCP (streamable HTTP):

{"mcpServers": {"hottub-search": {"type": "http", "url": "https://hottub.tech/mcp",
  "headers": {"Authorization": "Bearer hsk_…"}}}}

How much of this month you have used:

curl -s https://hottub.tech/v1/usage -H 'Authorization: Bearer hsk_…'

Keep your key secret: anyone who has it can spend your searches. Turn a key off at any time on your keys page; it stops working within a minute.

The same API answers at https://hottub.tech/v1 and https://api.hottubapi.com/v1; use either.

Command line

For agents and the shell, hottubtech prints short, numbered results that cost few tokens:

curl -fsSL https://hottub.tech/cli/install.sh | sh
hottubtech search best rust http client
hottubtech places plumber --near "Spokane, WA"
hottubtech help --agent

Your key: hottubtech auth login, then printf '%s\n' "$KEY" | hottubtech auth set. Agents that run only local MCP servers: hottubtech mcp.

Answers sized for agents

format=json|md|ndjson|text, fields=results.url,results.title and max_tokens=800: the answer is cut to your budget the same way every time, and truncated says what went.
depth=fast reads the index only, standard adds places, events and news where asked, deep reads everything and the first pages’ text. Hints intent, entity, types and time skip what you didn’t ask for.
Every element has id, kind, source and fetched_at. GET /v1/doc/{id} returns one element in full, POST /v1/batch runs up to 10 queries, stream=1 sends results first.

Feedback

Send POST /v1/feedback with an element’s fb token and a verdict: used, helpful, wrong, stale, irrelevant, spam, missing_info or broken_link. It is free and never counted as a search. Tokens name the element, never your query or you; a note (up to 280 characters) reaches only the people who fix things.

curl -s https://hottub.tech/v1/feedback -H 'Authorization: Bearer hsk_…' \
  -H 'Content-Type: application/json' -d '{"fb":"f1…","verdict":"stale"}'

Commerce links

What it is. Some results are pages at shops: a TV at a store, a hotel on a booking site. With Commerce links turned on, those results can carry a separate buy link next to the normal one. If someone buys through it, the shop pays a commission.

Your results stay the same. The normal link is always the plain page address. Buy links never change which results you get or their order. Turning Commerce links on or off changes nothing else in the answer.

It is off unless you turn it on. Turn it on for a key in your account, then ask for it with commerce=1. Calls without a key never get buy links.

You share in what it earns. When a buy link from your key's answer leads to a sale, you get a share of the commission once the shop's network confirms it: 50% (proposed). It is credited against your Search API bill each month.

Say it is a paid link. Each buy link comes with the words "Paid link: Hottub may earn a commission." Show them next to the link, every time.

Privacy. Buy links go straight to the shop's affiliate network, never through Hottub. Hottub does not track who clicks. The only tag on a link is a code that changes every day and names your key's day, never a person or what they searched.

Other people's links are left alone. If a page link already belongs to someone else's affiliate program, we leave it as it is and add nothing.

Commerce links terms

Keeping and showing results

You may store results and show them later, each with a link to its source page. Every answer to a key says so in terms.
A result marked "storable": false came from another search provider. Show it with that answer, but don’t keep it.
Directory places carry their own licence in provenance. Keep provenance.attribution when you show them.
Page text (content=1) belongs to its site. Quote it briefly and link to it.
Free plan: wherever people see the results, show “Results from Hottub Search” with a link to https://hottub.tech. Paid plans don’t have to.

Limits

Limits belong to the account, so more keys never mean more searches. Every answer says where you stand in the RateLimit and RateLimit-Policy headers (with a key, a minute window and a month window; without one, a minute and a day).

Answer	What it means
`429` `rate_limited`	Too many searches this minute. Wait for `Retry-After` seconds.
`429` `monthly_limit_reached`	The free searches for this month are used. More arrive on the 1st, or choose a paid plan.
`429` `spend_cap_reached`	You reached the monthly limit you set. Raise it, or wait for the 1st.
`429` `daily_limit_reached`	No key: this address used today’s 50 searches. More arrive at midnight UTC; a free key gives 2,500 a month.
`401` `key_invalid`	The key is wrong or was turned off.
`503` `search_unavailable`	Search had a problem. Nothing was counted. Try again shortly.

{"error": {"code": "rate_limited", "message": "Too many searches this minute…",
  "retry_after_seconds": 12, "plan": "free", "docs": "https://hottub.tech/developers"}}

Branch on the status and error.code, never on the message.

Counting and billing

Only answers you received are counted. A refused or failed search costs nothing.
Months are calendar months in UTC. Paid plans are billed by Stripe once a month for the searches you used.
Your monthly limit is a hard stop: searches past it are refused, never billed.
No key? The API stays free at 60 searches a minute and 50 a day (UTC) per address, without the right to keep results. A free key gives 2,500 a month.

Promises

Payment never changes the order of results. The service that ranks results is built without this price card.
No query is stored with a key: only how many searches it made each day.
Only answers you received are counted. A failed or refused search costs nothing.
Paid plans stop at the spending limit you choose; nothing is billed past it.

Price list search-api-2026-10-27.1. llms.txt · OpenAPI · Terms