Gateway

Web search

Web results through the Gateway: a query in, titles, links and snippets out, priced per search and returned with the same receipt headers as chat.

POSThttps://www.lobstack.ai/api/gateway/v1/search

Authenticate with a Lobstack API key as a bearer token, as for Chat Completions. Results come from the Brave Search API's own index and are served on Lobstack's key; there is no bring-your-own-key option for search. The Lobstack app uses this endpoint when a bot searches the web.

Request body

querystringrequired: What to search for. 1 to 400 characters after trimming.
countintegerdefault: 5: How many results, from 1 to 10. Fewer may come back.
metadataobject: Not sent to the provider. metadata.client is read as the client tag. See Clients.

Response

{
  "query": "why did the deploy roll back",
  "results": [
    {
      "title": "Rollbacks and failed health checks",
      "url": "https://example.com/rollbacks",
      "snippet": "A deploy rolls back when the new version fails its health check…"
    }
  ]
}

Snippets are plain text: the provider's highlighting markup is removed and entities are decoded. Every result carries its URL, so an answer built on it can cite its source.

Price and metering

web-search is priced per search, not per token: $0.00625 a search ($6.25 per 1,000). That is Brave's published price times the same rate the Gateway applies to model calls, checked on 2026-09-29. A search that fails at the provider costs nothing.

Each search writes a ledger row with zero tokens and that cost, draws down the same allowance as model spend, and counts toward client budgets and the rate limit. The receipt headers are the ones listed on Metering & cost, with x-lobstack-model: web-search.

Errors

Status	When
400	A missing, empty or over-long query, or a count outside 1 to 10.
401	The API key is missing, invalid or revoked.
402	The allowance or the client's budget is spent.
429	The per-key rate limit, or the search provider's own limit. Retry after a pause.
502	The search provider failed. Nothing is charged.
503	Search is not configured on this deployment. The body is `{"error":"search not configured"}`.
504	The search provider did not answer within 10 seconds.

Error shapeEvery error except the 503 above has the Gateway's usual body, with a request_id. See Errors & retries. Query text is never logged or stored; the trace records its length only.

Examples

curl -i https://www.lobstack.ai/api/gateway/v1/search \
  -H "Authorization: Bearer $LOBSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "why did the deploy roll back", "count": 5}'