Web search

Authenticate with a Lobstack API key as a bearer token, as for Chat Completions. Any key with the inference scope can search, whatever runs the agent's models: Lobstack, your own provider key, or GitHub Copilot. Results come from the Brave Search API's own index and are always served on Lobstack's key, so every search is billed like a call on Lobstack's keys. The Lobstack app uses this endpoint first when an agent searches the web, and falls back to your own search or the browser when it answers 402 or 503.

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, the same way as model calls on Lobstack's keys. Inside your plan's included usage, and on the Free plan's starting credit, a search costs Brave's published price: $0.005 ($5.00 per 1,000). Past the included usage it is provider price + 50%: $0.00750 a search, from purchased credit. Brave's price was 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 limits. The receipt headers are the ones listed on Metering & cost, with x-lobstack-model: web-search and x-lobstack-mode: managed.

The same query (ignoring case and spacing) with the same count, from the same organization within 10 minutes, may be answered from a short cache. A cached answer is free: it carries x-lobstack-cache: hit, a cost of 0 and no ledger row, and still shows in Logs. A fresh answer carries x-lobstack-cache: miss.

Errors

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}'