Web search

Tools & integrations → Web search (/admin/search). The provider OCI searches with, its key or address, and the one switch that turns web search on or off for the instance.

SerpApi and SearchApi are different companies; a key from one is rejected by the other. Hosted providers use their own fixed endpoints. A key belongs to one provider: switching provider removes the saved key, and the page asks for the new one before search can be switched on. Keys are encrypted and never shown again.

Test search runs one sample search with the provider and key or address on the page, saved or not, and says whether it worked or what the provider replied (for example, that it rejected the key). Nothing is saved. Each test is audited as search.test, with the provider and outcome only.

Who gets searchCopy Anchor Link

People are offered Search only when it can actually run: the switch is on, a provider is chosen, and it has its key or address. Until then the control is removed rather than offered and failing; the page says whether search is available and why not. Each role must also allow Web search on Roles & access.

How a search runsCopy Anchor Link

• With a model tagged Tool calling, and the web_search tool allowed for the role, the model searches when it chooses, possibly several times, up to 10 results each, and cites results as sources.
• With other models, or when the role's web_search tool switch is off, OCI runs one search before the reply, using the message as the query.

A search that times out, cannot reach the provider or gets a server error is retried once, then goes to the fallback provider if there is one. A rejected key or a rate limit is reported straight away. A search gives up within about 25 seconds. A failed search never fails the reply: it shows Web search failed with the reason (such as "SerpApi rejected the web search API key (HTTP 401)"), and the model is told current sources could not be checked. Provider errors are logged without the query or key.

Fallback providerCopy Anchor Link

Under Fallback provider, choose a second provider for when the first one is slow or down. A search that times out, cannot reach the provider or gets a server error (HTTP 5xx) is tried once more; if it fails again, the same search goes to the fallback. A rejected key, a used-up quota (HTTP 429) or another error you need to fix is reported as it is and never passed to the fallback.

• The fallback asks for exactly what its provider needs: an address for SearXNG, a key for the others. Its key is encrypted and never shown again, like the first provider's; switching the fallback to another provider removes its saved key.
• It must be a different service: a hosted provider cannot be its own fallback, and a SearXNG fallback must be at a different address.
• With a fallback chosen, each attempt at the first provider waits at most 8 seconds (15 without one), so the fallback still has time to answer; a search still gives up within about 25 seconds in all.
• The reply records which provider answered. Its search details say so, and a tool step the fallback answered reads, for example, Searched the web for 'library hours' · 5 results · via Brave Search (fallback). When both fail, the error names both.
• Test search tests the fallback too, separately, and reports each result. The audit entry records both providers and outcomes.
• A fallback missing its key or address is not used. Search still works, and the setup checklist says why the fallback is not used.

Logs say which provider failed, how and when, and that a search fell back, never the query or a key. The metrics oci_web_searches_total and oci_web_search_duration_seconds count searches by provider, by primary or fallback, and by outcome.