Skip to navigation
aVenture APISearch and IdentifySearch

Search the Live Web

View as Markdown

Runs a live web search and returns its results, or a stored result when the same query was searched recently. Use it for external facts a stored record lacks, such as a publication or release date, press coverage, or an app-store listing. Each successful search uses one web search from the signed-in account’s monthly allowance. Past it, a subscriber with additional usage on pays 2.5 cents per search; otherwise the call answers 429 with a usage-limit message and upgrade links. A query naming too few distinct words (a bare brand, or a brand plus a number) is refused with 422 before any charge; name what you are looking for and a disambiguator such as the domain. Set provider to EXA for Exa’s instant search or EXA_DEEP for its slower, broader deep search; both answer synchronously. When the default search is still running after aVenture’s live wait, the call answers 503 with Retry-After; send Prefer: respond-async to receive 202 with a Location status URL instead, and poll it after Retry-After. Neither charges an allowance search.

Authentication

AuthorizationBearer

Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token

Headers

Idempotency-KeystringOptionalformat: "(?U)(?!\s*$)[^\p{Cc}]+"1-255 characters
Replay key for this account's exact search request, up to 255 characters
PreferstringOptional

Send respond-async to receive a pollable job when a live web search is still running; an Exa provider answers live.

Request

This endpoint expects an object.
searchstringRequired
Search text sent to the upstream web search provider
allowSuspectedShellStripboolean or nullOptional
Set true only when an unmarked amount in the search text is intentional.
bypassCachebooleanOptionalDefaults to false
Skip cache lookup and refresh from the search provider
cacheKeystring or nullOptional
Stable lookup text for cache keying when generated search text varies between runs
deferredAiOverviewbooleanOptionalDefaults to false

Wait in-request for Google’s AI Overview when Google defers it to a follow-up request, as it does for most company and person lookups: one extra SerpAPI search per overview not already stored. An explicit true also reruns a stored search older than SerpAPI’s one-hour cache to get a fresh token (its one-minute overview token expired and the cache would return it unchanged). Without it, no deferred overview is fetched; one an earlier fetch stored still comes back at no extra cost. A fetch that returns no overview is not retried for six hours. An overview Google returns inline always comes back in aiOverview at no extra cost. Exa results never carry one.

languagestring or nullOptional
Search language code
providerstring or nullOptional

Provider to search; omitted keeps the default, SerpAPI. EXA runs Exa’s instant search with highlights and never falls back to SerpAPI: an Exa failure answers 503. EXA_DEEP runs Exa’s slower, broader deep search (higher recall for market and provider questions, about 3-6 s) and falls back to SerpAPI on an Exa failure. Both Exa providers answer synchronously (Prefer: respond-async does not apply), are stored apart from SerpAPI results, and are charged like any search.

regionstring or nullOptional
Search region code
resultLimitinteger or nullOptional
Maximum number of normalized results to keep
retrievedForobject or nullOptional

Company or person this search is about; the stored result is filed under that record on a fetch or a cache hit.

sourcestring or nullOptional<=64 characters
Optional label for the calling application, up to 64 characters, stored with the search for attribution and abuse review.
deepbooleanOptionalDefaults to falseDeprecated

Deprecated alias for provider: EXA_DEEP; true with any other provider is refused with 400.

Response headers

X-RateLimit-Limitinteger

Requests allowed per client IP in the current rate-limit window.

X-RateLimit-Remaininginteger

Requests left before the tightest applicable rate-limit bucket rejects.

X-RateLimit-Resetinteger

Seconds until the exhausted rate-limit bucket admits another request; 0 when none is exhausted.

Response

OK
documentobject

Source-document ledger row backing this result

resultlist of objects
Normalized result items in provider rank order
searchobject
Web search request represented by this result
aiOverviewobject or nullOptional

Google’s AI Overview: returned whenever Google answers inline or its deferred overview is stored (fetched by this or an earlier search that set deferredAiOverview); null when Google produced none or no such fetch stored its deferred overview

answerBoxobject or nullOptional

Google’s direct answer box; null when the page shows none

knowledgeGraphobject or nullOptional

Google’s knowledge panel; null when the page shows none

relatedQuestionlist of objects or nullOptional

Google’s “People also ask” questions; null when the page shows none

relatedSearchlist of strings or nullOptional

Google’s related searches; null when the page shows none

sportsResultobject or nullOptional

Google’s game spotlight; null when the page shows none

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
409
Conflict Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error