Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Endpoints / Retrieval

Search

POST/v1/search

Run provider-neutral web or news search through Lazu. Hosted api.lazu.ai currently enables Tavily, Serper and Jina; self-hosted operators can add Exa or Brave through the same search-backend system.

What it returns

Normalized results

Every backend maps into title, url, snippet, optional content, published_at, score and source.

Auditable routing

The response includes the selected backend and route receipt. Request logs store the same routing metadata for support and billing reconciliation.

Hosted configuration

The /v1/search implementation supports Tavily, Serper, Exa, Jina and Brave, but the hosted Lazu deployment is configured with this active set:

BackendHosted statusCapabilitiesNotes
TavilyEnabledweb_search, web_fetch, answerSupports include_answer and search_depth; advanced is 2 units.
SerperEnabledweb_searchMaps country / region, language and time_range when provided.
JinaEnabledweb_search, web_fetchUses https://s.jina.ai; best for retrieval-style snippets.
Exa / BraveSupportedweb_search after operator setupAvailable for self-hosted or admin-configured deployments.

Hosted backends currently use the default backend policy: up to 10 results per request and an 8s upstream timeout. If you send a larger max_results, Lazu clips it to the selected backend policy.

Request body

querystring
required

Search query. The MVP supports one query per request.

typestring
nullable
webnews

Search vertical. Defaults to web.

backendstring
nullable

auto, a provider name such as tavily or serper, or a configured backend ID/name. Defaults to auto.

regionstring
nullable

Region hint. Serper maps this to gl; other providers may ignore unsupported regions.

languagestring
nullable

Language hint such as en or zh-CN.

time_rangestring
nullable
dayweekmonthyear

Freshness hint. Providers that cannot map the value may ignore it.

max_resultsinteger
nullable

Number of results to return. Defaults to 10 and is capped by the selected backend policy.

search_depthstring
nullable
basicadvanced

Provider depth hint. Tavily advanced uses two billable credits.

include_answerboolean
nullable

Include a provider answer when the selected backend returns one. Lazu does not generate its own final answer in this endpoint.

include_raw_contentboolean
nullable

Include raw or cleaned content when the provider returns it. Defaults to false.

include_domainsstring[]
nullable

Restrict results to domains. Token-level domain allowlists still apply.

exclude_domainsstring[]
nullable

Exclude domains when supported by the selected backend.

include_provider_payloadboolean
nullable

Return the provider-native payload for debugging. Defaults to false.

provider_optionsobject
nullable

Advanced provider passthrough. Only the selected provider's object is used, for example {"serper":{"tbs":"qdr:d"}}.

Response

Search response
json
{
"query": "latest OpenAI web search API changes",
"results": [
  {
    "title": "Web search - OpenAI API",
    "url": "https://platform.openai.com/docs/guides/tools-web-search",
    "snippet": "Use web search in the Responses API...",
    "content": null,
    "published_at": null,
    "score": 0.91,
    "source": "web"
  }
],
"usage": {
  "web_search_requests": 1,
  "web_search_billable_units": 1
},
"provider_trace": {
  "backend": "tavily"
},
"route_receipt": {
  "selection": "auto",
  "selected_backend": "tavily",
  "chose_provider": "tavily",
  "candidates": ["tavily:Tavily"],
  "rejected": [],
  "downgraded": false,
  "fallback_count": 0,
  "decision_reason": "selected"
}
}
results[]object[]

Normalized search result list. content is only populated when raw content was requested and returned by the backend.

usage.web_search_requestsinteger

Lazu search request count, normally 1.

usage.web_search_billable_unitsinteger

Provider billing units used for the charge. Tavily basic is 1 unit, Tavily advanced is 2 units, and Serper or Jina is normally 1 successful query.

provider_trace.backendstring

Actual provider selected after routing.

route_receiptobject
nullable

Candidate, fallback and rejection metadata. The same data is stored in the request log.

Billing

Search backends are priced from their configured search_price. The value is the USD price per provider billing unit, not always per HTTP request. The hosted Tavily, Serper and Jina backends currently have no explicit

search_price configured, so Lazu records web_search usage and bills $0 for the search line item until an operator configures a price or provider-cost passthrough.

BackendUnit mapping
Tavilybasic = 1 credit; advanced = 2 credits
Serper1 successful query = 1 unit
Jina1 successful query = 1 unit

Failed upstream calls, timeouts and invalid requests are refunded according to the normal Lazu billing rules.

See also