vaaya / docs / reference

SuperSearch

vaaya/supersearch (flat 5¢) is the retrieval routing engine as a single executable action. Hand it an intent; it plans a multi-source retrieval, races independent indexes, chains full-content extraction when fidelity matters, and returns normalized evidence where every item cites its transaction id. The internal source calls are included in the flat price — you pay 5¢, not the sum of the rungs.

The simplest call — just a query

Price

flat 5¢ — internal source calls included

Facets

12 search facets + scrape + social

Output

normalized evidence, each item cites its transaction id

With only a query, an intent classifier authors the routing frame for you — which facets to search, whether to race indexes, whether to pull full content.

curl -X POST https://vaaya.ai/api/run/vaaya/supersearch \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "what changed in the WebTransport spec this year"}'

Route it yourself: facets

Adding any frame field skips the classifier. facets (one or more, default ["web"]) picks the source ladders; each facet fires its own ladder concurrently and the evidence is merged.

Frame modifiers

• timeCritical: true — race two independent indexes (Exa + Brave for web, Brave News + Tavily for news) for breaking / “latest” queries.
• fidelityRequired: true — fetch the full page content (chains search → extraction), not just snippets.
• recencyDays — restrict to recent results.
• domains / excludeDomains — include or exclude sites.
• maxResults — cap the merged evidence list.
• urls: [...] — skip search and extract these pages directly.
• asOf: "YYYYMMDD" — fetch the archived copy via the Wayback Machine.

Scrape facets — fetch these URLs

Pass urls with a scrape facet to use SuperSearch as a laddered, managed extractor. Both are fetch-only (they require urls) and are never chosen by the classifier — route to them explicitly.

• facets: ["scrape"] — cheapest-first ladder that escalates each URL on a miss: bulk no-JS extraction → JS rendering → anti-bot scraping → residential proxies. Use for “get the clean content of these pages” when a plain fetch might be blocked.
• facets: ["scrape-hard"] — go straight to residential proxies + headless Chrome for anti-bot / geo-walled pages. One page per call — it’s the priciest rung.

curl -X POST https://vaaya.ai/api/run/vaaya/supersearch \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "facets": ["scrape"],
    "urls": ["https://example.com/pricing", "https://example.com/changelog"]
  }'

For direct control over the individual rungs — vendor choice, formats, structured extraction, crawls — see Web scraping.

Social facet — search one platform

facets: ["social"] + platform (one of tiktok, instagram, youtube, twitter, weibo, reddit) + query (the keyword) returns raw posts for the platform. Caller-driven — pick the platform explicitly; the classifier never chooses it. Defaults to twitter. For profile/comment/follower endpoints beyond keyword search, see Social data.

SuperSearch vs. a raw search vendor

Pick SuperSearch when the value is in the bundling: one call that searches, corroborates across indexes, optionally pulls full page content, and hands back cited evidence — without you orchestrating an exa/search → scrape chain. It’s the best default for:

• “Search + read the pages” in one shot (fidelityRequired).
• Documentation lookups that must keep full code and markdown (facets: ["docs"]).
• Time-critical questions where a second independent index matters (timeCritical).

Pick a raw vendor from Web search when a single 1¢ call is enough, or when you need something SuperSearch doesn’t do:

• A specific vendor feature — exa/search category: "people" for GTM people-discovery, Tavily’s include_answer, linkup/deep-search (5¢) or parallel/task (10–30¢) for deep async research, firecrawl/search for content-with-hits.
• A plain one-off 1¢ search where the 5¢ bundle isn’t worth it.
• A facet SuperSearch doesn’t cover yet — it routes web, docs, news, academic, code, public-filings, funding, financials, legal, nonprofits, regulatory, and compliance (search), scrape / scrape-hard (fetch), and social (per-platform) today. For GTM/contacts, on-chain, and other facets, call the specific vendor directly.

SuperSearch vs. consult

vaaya/consult is the router — it tells you which call(s) to run. SuperSearch is a call you actually run. They compose: for a search or research intent, consult can simply recommend vaaya/supersearch with a plain-English query and let the engine plan the rest. Reach past SuperSearch to name specific vendors only when the intent needs a capability it doesn’t cover.