// Use when the user wants real-time web, news, or X/Twitter results with AI-summarized answers and citations — Grok Live Search via BlockRun. Cheapest path for "what just happened" questions where freshness beats neural-semantic ranking.
Use when researching products, finding academic papers, discovering competitors, reading webpage content, or getting cited answers grounded in real web sources. Use over generic search when semantic relevance matters.
Use when the user needs to run isolated code remotely — a disposable container, optional GPU access (T4 → H100), or a safer place for untrusted / heavy code. Prefer local execution for normal repo work; use Modal sandboxes for isolation, hardware access, or one-shot heavy compute.
Use when the user wants phone-number intelligence (lookup, carrier, line type, SIM-swap / call-forwarding fraud signals), US/CA number provisioning (rent a phone number), or outbound AI voice calls (Bland.ai under the hood — schedule, confirm, follow-up). Pay per call in USDC.
Use when the user wants crypto data — token prices, on-chain SQL, prediction-market positions, CEX order books, wallet labels/net-worth, social mindshare, news, or a Surf-1.5 chat answer with citations. 84 endpoints across exchange, on-chain, wallet, social, prediction, news, search, and chat — one API, pay-per-call in USDC via x402. Settles directly to Surf's Base treasury; no Surf account needed.
Use when user asks about event probabilities, prediction market odds, what people are betting on, Polymarket or Kalshi prices, sports markets, wallet identity / clustering, or wants to find markets on a specific topic (elections, crypto, sports, macro events). Predexon v2 endpoints (canonical cross-venue markets, sports, wallet identity, keyset pagination) live in production as of 2026-05.
Use when generating or editing images via `blockrun_image` — especially with GPT Image 2, DALL-E 3, or Flux for posters, UI mockups, marketing assets, product shots, or anything with on-image text. Turns vague user requests ("make me a cool poster") into structured, text-accurate prompts that actually render what you asked for.
| name | search |
| description | Use when the user wants real-time web, news, or X/Twitter results with AI-summarized answers and citations — Grok Live Search via BlockRun. Cheapest path for "what just happened" questions where freshness beats neural-semantic ranking. |
| triggers | ["live search","grok live","what just happened","real time news","breaking news","today's news","search with citations","cited search","x search","twitter search","news search"] |
Real-time web + X/Twitter + news search with AI-summarized results and citations. $0.025 × max_results (default 10 → $0.25 per call). Best for fresh queries; for semantic / neural research use blockrun_exa instead.
blockrun_search({ body: {
query: "what's the consensus on the Fed's next move",
sources: ["web", "news"],
max_results: 10
}})
| Field | Required | Type | Notes |
|---|---|---|---|
query | yes | string | Natural-language search query |
sources | no | string[] | Subset of ["web","x","news"]. Default: all three. Does NOT multiply price. |
max_results | no | number | 1–50, default 10. Drives the price at $0.025 each. |
from_date | no | string | YYYY-MM-DD lower bound on result date |
to_date | no | string | YYYY-MM-DD upper bound |
| User intent | sources setting |
|---|---|
| Breaking news / today's headlines | ["news"] |
| What's the CT / KOL sentiment on X | ["x"] |
| Backgrounder / explainer / docs | ["web"] |
| General "find current info" question | omit — defaults to all three |
blockrun_search({ body: { query: "Ethereum ETF approval SEC", sources: ["news","web"], max_results: 8 } })
Cost: $0.025 × 8 = $0.20.
blockrun_search({ body: { query: "Solana outage today", sources: ["x"], max_results: 15 } })
Cost: $0.025 × 15 = $0.375.
blockrun_search({ body: {
query: "Ethereum Pectra upgrade",
sources: ["web","news"],
from_date: "2026-02-17"
}})
Cost: $0.025 × 10 (default) = $0.25.
| Use case | Tool |
|---|---|
| "What's happening right now?" — freshness matters | blockrun_search |
| "Find the canonical paper on X" — semantic relevance matters | blockrun_exa |
| "Pull the full text of these 5 URLs" — content fetch | blockrun_exa contents |
| "Cited answer to a question" | both work; blockrun_exa answer is grounded in pre-indexed corpus, blockrun_search searches the live web |
max_results: 20 with one source or three sources both cost $0.025 × 20 = $0.50. Pass a smaller max_results to cap spend.POST /v1/search