# Web search

URL: https://bridge.wekoya.tech/docs/search
Updated: 2026-11-08

> Search the live web from your app on POST /v1/search: news, prices and rates, what people are saying about a brand, anything a model cannot know from its…

Search the live web from your app on `POST /v1/search`: news, prices and rates, what people are saying about a brand, anything a model cannot know from its training. You get the pages found, each with its title, link, a short extract and the date when the page gives one. Ask for `answer: true` and you also get a short answer written from those pages, citing them as [1], [2], so your app can show where each fact came from.

```
curl https://wekoya-api.wekoya.tech/v1/search \
  -H "Authorization: Bearer $WEKOYA_API_KEY" -H "Content-Type: application/json" \
  -d '{ "query": "naira to dollar rate today", "max_results": 5, "recency": "day", "country": "NG", "answer": true }'

{
  "object": "search",
  "query": "naira to dollar rate today",
  "results": [
    { "title": "Naira closes at ₦1,329 to the dollar",
      "url": "https://punchng.com/naira-closes/",
      "snippet": "The naira closed at ₦1,329.44 on Thursday…",
      "published_at": "2026-10-15T09:00:00.000Z" },
    …
  ],
  "answer": "The naira closed at ₦1,329.44 to the dollar on 15 October 2026 [1].",
  "citations": [{ "number": 1, "url": "https://punchng.com/naira-closes/", "title": "Naira closes at ₦1,329 to the dollar" }],
  "wekoya": { "cost": 10.53, "currency": "NGN" }
}
```

- `query`: what to search for, up to 400 characters. The only field you must send.
- `max_results`: 1 to 10. Default 5.
- `recency`: `day`, `week`, `month` or `year` for recent pages only; `any` (the default) for all.
- `site`: one website only, like `punchng.com`. Its subdomains count.
- `country`: a two-letter code such as `NG`, to favour that country's results.
- `answer`: `true` for a short answer with `citations`. `answer` is `null` when the pages do not answer the question, rather than a guess.

#### What it costs
One flat price per search: about ₦7.02, or ₦10.53 with an answer, shown in `wekoya.cost` and the `X-Bridge-Cost` header. A search that finds nothing is still a search and is charged. A search that fails answers 503 `search_unavailable` and costs nothing; try again after a short pause. End users (`X-Bridge-End-User`), app budgets and key limits apply as for every other call. A key with a model allow-list needs `web-search` on its list, and a guest key needs the `search` use.