エンドポイント / Retrieval

POSThttps://api.lazu.ai/v1/search

Search

Lazu 経由で provider-neutral な web/news search を実行します。Hosted api.lazu.ai では現在 Tavily、Serper、Jina が有効です。self-hosted の operator は同じ Search Backend 仕組みで Exa や Brave も追加できます。

課金検索料金はバックエンドと課金単位によって異なります。料金とレーン ↗

What it returns

Normalized results

backend ごとに title、url、snippet、 optional content、published_at、score 、source へ mapping します。

Auditable routing

response は selected backend と route receipt を含みます。同じ routing metadata が request logs に保存され、support と billing reconciliation に使えます。

Hosted configuration

/v1/search の実装は Tavily、Serper、Exa、Jina、Brave を support しますが、現在表示される検索価格と、リクエスト詳細の web_search 明細を照合してください。過去の例やデプロイ設定から無料と推測しないでください。

Backend	Hosted status	Capabilities	Notes
Tavily	Enabled	`web_search`, `web_fetch`, `answer`	`include_answer` と `search_depth` を support。`advanced` は 2 units。
Serper	Enabled	`web_search`	`country` / `region`、`language`、`time_range` を mapping します。
Jina	Enabled	`web_search`, `web_fetch`	`https://s.jina.ai` を使い、retrieval 形式の snippet に向いています。
Exa / Brave	Supported	operator 設定後に `web_search` 対応	self-hosted または admin-configured deployment 向けです。

Hosted backends は現在 default policy を使っています。1 request あたり最大 10 results、upstream timeout は 8s です。max_results がそれより大きい場合、 Lazu は selected backend policy に合わせて切り詰めます。

Request body

querystringrequired

search query。MVP は 1 request につき 1 query を support します。

typestringnullable

search vertical。default は web。

webnews

backendstringnullable

auto、provider name（例：tavily）、または configured backend ID/name。default は auto。

regionstringnullable

region hint。Serper は gl に mapping します。

languagestringnullable

language hint。例：en、ja。

time_rangestringnullable

freshness hint。provider が mapping できない value は無視されることがあります。

dayweekmonthyear

max_resultsintegernullable

結果数。default は 10 で、selected backend policy の上限が適用されます。

search_depthstringnullable

provider depth hint。Tavily advanced は 2 billable credits。

basicadvanced

include_answerbooleannullable

selected backend が answer を返す場合に含めます。Lazu はこの endpoint 内で最終回答を生成しません。

include_raw_contentbooleannullable

provider が raw content または cleaned content を返す場合に透過します。 default は false。

include_domainsstring[]nullable

検索対象 domain を制限します。token-level domain allowlist は引き続き適用されます。

exclude_domainsstring[]nullable

selected backend が support する場合に domain を除外します。

include_provider_payloadbooleannullable

provider-native payload を debugging 用に返します。default は false。

provider_optionsobjectnullable

advanced provider passthrough。selected provider の object だけが使われます。例：{"serper":{"tbs":"qdr:d"}}。

Response

Search responsejson

{
"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。raw content を request し、backend が返した場合だけ content が入ります。

usage.web_search_requestsinteger

Lazu search request count。通常は 1。

usage.web_search_billable_unitsinteger

charge に使われる provider unit。Tavily basic は 1、Tavily advanced は 2、 Serper と Jina は通常 1 successful query です。

provider_trace.backendstring

routing 後に実際に選ばれた provider。

route_receiptobjectnullable

candidates、fallback、rejection metadata。同じ情報が request log に保存されます。

Billing

Search backend は configured search_price から課金されます。これは provider billing unit あたりの USD 価格であり、常に HTTP request 単位とは限りません。現在の hosted Tavily、Serper、Jina backends には明示的な

search_price が設定されていないため、Lazu はweb_search usage を記録しますが、search line item は $0 です。 operator が価格または provider-cost passthrough を設定したあとに、その設定で課金されます。

Backend	Unit mapping
Tavily	`basic` = 1 credit、`advanced` = 2 credits
Serper	1 successful query = 1 unit
Jina	1 successful query = 1 unit

upstream failure、timeout、invalid request は通常の Lazu billing rules に従って refund されます。