Vertex AI grounding with your search API

One tool block, and nothing to deploy

Google's guide to grounding with your search API has you build an endpoint and put it behind API Gateway. SpecStream is that endpoint already, for the whole live web. Add one retrieval tool to the request and keep the rest of your code.

# pip install --upgrade google-genai
# export GOOGLE_CLOUD_PROJECT=your-project GOOGLE_CLOUD_LOCATION=global GOOGLE_GENAI_USE_ENTERPRISE=True
import os
from google import genai
from google.genai.types import ExternalApi, GenerateContentConfig, HttpOptions, Retrieval, Tool

client = genai.Client(http_options=HttpOptions(api_version="v1"))

specstream = Tool(
    retrieval=Retrieval(
        external_api=ExternalApi(
            api_spec="SIMPLE_SEARCH",
            endpoint="https://api.specstream.ai/vertex/search",
            api_auth={"apiKeyConfig": {"apiKeyString": os.environ["SPECSTREAM_API_KEY"]}},
        )
    )
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Who won the most recent Formula 1 race?",
    config=GenerateContentConfig(tools=[specstream]),
)
print(response.text)

The same tool in a REST request to generateContent:

{
  "contents": [{"role": "user", "parts": [{"text": "Who won the most recent Formula 1 race?"}]}],
  "tools": [{
    "retrieval": {
      "externalApi": {
        "api_spec": "SIMPLE_SEARCH",
        "endpoint": "https://api.specstream.ai/vertex/search",
        "apiAuth": {"apiKeyConfig": {"apiKeyString": "YOUR_SPECSTREAM_KEY"}}
      }
    }
  }]
}

The call Gemini sends, and what comes back

Gemini sends POST with the JSON body {"query": "..."} and adds your key to the address as ?key=. SpecStream answers with the JSON array Google's schema asks for: one object per result, each with snippet and uri, and an empty array when nothing matches. Each call returns up to 10 results. Errors come back in Google's error form.

# The call Gemini sends: the query in the body, your key as key= in the address
curl "https://api.specstream.ai/vertex/search?key=$SPECSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "who won the most recent Formula 1 race"}'

# [{"snippet": "...", "uri": "https://..."}, ...]

$1 per 1,000 searches, on every Gemini model

Each search Gemini makes through this endpoint costs $0.001. Grounding with Google Search costs $14 per 1,000 grounding queries on Gemini 3 and Gemini 4 past 5,000 free a month, and $35 per 1,000 grounding prompts on Gemini 2.0 and 2.5. SpecStream bills from a prepaid balance that never expires, and a new account starts with $10 of credit.

The most accurate web search API in the world

On SimpleQA Verified the SpecStream Search API scores 97.9 F-score on all 1,000 official questions, 978 of them correct. On WideSearch it scores 64.0 item F1 and 43.4 row F1 on all 200 official tasks. The Extract API scores 0.908 F1 on WCXB. Every score and its method is on the benchmarks page.

Use it beside Google Search or your own data

A generation request takes up to 10 grounding sources. Keep Grounding with Google Search, Vertex AI Search or Elasticsearch where they serve you, and add SpecStream as one more retrieval tool for the live web.

You decide what is kept, on each key

Give Gemini a key with zero_retention and a search made with it keeps no request text and no answer after the reply. It is not in the history and its log lines carry neither. The charge keeps the account, the key, the request ID, the price and the time. spend_cap_cents is the most the key can spend.

curl -X POST https://api.specstream.ai/v1/account/keys \
  -H "Authorization: Bearer $SPECSTREAM_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "vertex-grounding", "scopes": ["account:read", "finds:spend"], "spend_cap_cents": 500000, "zero_retention": true}'

Search, pages and rows on one key

The same key reads up to 20 pages or documents a call with the Extract API at $0.80 per 1,000 pages, and a page with no text is not charged. Deep Search takes a request in plain words and returns every match on the live web as structured rows, at 5¢, 15¢ or $1 a row, with a source URL on every value.

Grounding with Google Search

Google's own index, built into Gemini. $14 per 1,000 grounding queries on Gemini 3 and Gemini 4 after 5,000 free a month, billed only when a prompt returns a source. SpecStream grounds the same models at $1 per 1,000 searches. More on the Grounding with Google Search alternative page.

Web Grounding for Enterprise

A web index Google offers to highly regulated industries, with compliance controls, on the same $14 per 1,000 price line as Google Search. SpecStream keeps nothing from a search made with a zero_retention key and costs $1 per 1,000.

Grounding with Parallel

Parallel's search API, sold on Google Cloud Marketplace or on your own Parallel key, from $1 per 1,000 requests. SpecStream costs $1 per 1,000 searches through any project that can call an endpoint, and scores 97.9 F-score on SimpleQA Verified.

Grounding with Exa

Exa's search API on your own Exa key, at $7 per 1,000 auto searches. SpecStream costs $1 per 1,000 searches and reads the live web at the moment of the call.