Web Search API Usage Guide

Run a web search and get structured results — titles, URLs, snippets, scores and positions — back as JSON. One request, one response; there is no job to poll.

Endpoint: GET https://api.radienthq.com/v1/tools/search?query=… — query-string parameters in, raw JSON out (no envelope), $0.01 per request.

#Quickstart

bash

curl -G https://api.radienthq.com/v1/tools/search \
  -H "Authorization: Bearer $RADIENT_API_KEY" \
  --data-urlencode "query=golang echo framework" \
  --data-urlencode "max_results=2"

A real response (snippets trimmed here; … marks the trim):

json

{"results":[{"title":"echo package - github.com/labstack/echo/v4 - Go Packages","url":"https://pkg.go.dev/github.com/labstack/echo/v4","content":"…","score":0.8259413,"position":1},{"title":"Building Microservice using Golang Echo framework","url":"https://medium.com/cuddle-ai/building-microservice-using-golang-echo-framework-ff10ba06d508","content":"…","score":0.8215175,"position":2}],"query":"golang echo framework","provider":"…","total_found":2}

#Request parameters

All parameters travel in the query string, not a JSON body.

Parameter	Type	Required	Notes
`query`	string	Yes	The search query. Empty or missing is a 400.
`max_results`	integer	No	How many results to ask for. The search service may return fewer (it caps its own maximum); when omitted, its default applies. A non-numeric value is ignored and the default is used.
`include_raw`	boolean	No	`true` adds each result's full page text as `raw_content` — useful for feeding a model, at the cost of a much larger response.
`search_depth`	string	No	`basic` or `advanced`. A hint to the search service; the effect and any price difference depend on it.
`domains`	string	No	Comma-separated hostnames to restrict the search to, e.g. `pkg.go.dev,github.com`.

#Response fields

Field	Notes
`results`	Array of results, each with `title`, `url`, `content` (a snippet), and usually `score` and `position`. With `include_raw: true`, each entry also carries `raw_content`.
`query`	The query as the search service resolved it.
`provider`	The search service that served the request (informational).
`total_found`	How many results the service reported, when it reports one.

#Pricing

Each request is metered at $0.01, flat — one unit per call, regardless of max_results or include_raw. The charge travels in the response as a top-level cost object, from a live call:

json

"cost": { "v": 1, "amount_usd": 0.01, "basis": "billed", "units": 1, "unit": "search", "unit_price_usd": 0.01, "provider": "tavily", "tool_type": "web_search", "usage_record_id": "6acabfd280f7de3d24c9826a" }

Metering happens per request even when the search service fails to answer, so a 500 from this endpoint is still recorded as a metered call; a 400 (missing query) is rejected before metering and costs nothing. Details of balance behaviour are in Radient Pass, and the object's fields in Cost reporting.

#Errors

Status	Meaning
400	Missing or empty `query`.
401	Missing or invalid credentials.
402	Insufficient credits — see Radient Pass.
500	The search service failed or refused the query (e.g. a query below its minimum length). Reformat the query and retry.
429	The search service is busy; retry after a moment.
503	Search is temporarily unavailable; retry later.

Real bodies (… marks text trimmed in this page):

json

{"error":"[bad_request] Query parameter is required"}

json

{"error":"[internal] Search failed: …"}

json

{"error":"missing Authorization header"}

json

{"error":"insufficient credits"}

#Tips

Quote and URL-encode the query; use curl -G --data-urlencode rather than pasting text into the URL.
Start with a small max_results; the service bills the same $0.01 whether you ask for 2 or 20.
Use include_raw only when you need the page text — it can multiply response size by hundreds.
domains is the cheapest way to bias a search towards authoritative sources for a topic.

For the full endpoint list, see the API Reference.