Custom Search API example

curl

curl -G "https://api.specstream.ai/customsearch/v1" \
  --data-urlencode "key=$SPECSTREAM_API_KEY" \
  --data-urlencode "q=open source vector databases" \
  -d num=10 -d start=1

The key also works in the X-Goog-Api-Key header or as Authorization: Bearer.

Python with requests

import os
import requests

reply = requests.get(
    "https://api.specstream.ai/customsearch/v1",
    params={
        "key": os.environ["SPECSTREAM_API_KEY"],
        "q": "open source vector databases",
        "num": 10,
    },
    timeout=30,
)
reply.raise_for_status()
for item in reply.json().get("items", []):
    print(item["title"], item["link"], item["snippet"])

The Python page has the urllib version and a paging loop.

JavaScript with fetch

const params = new URLSearchParams({
  key: process.env.SPECSTREAM_API_KEY,
  q: "open source vector databases",
  num: "10",
});

const response = await fetch(`https://api.specstream.ai/customsearch/v1?${params}`);
const data = await response.json();
if (!response.ok) throw new Error(data.error.message);

for (const item of data.items ?? []) {
  console.log(item.title, item.link, item.snippet);
}

This runs in Node 18 and later, Deno, Bun and edge functions. Keep the key on the server.

The reply, field by field

The reply has Google's shape. Values here are cut to their type.

{
  "kind": "customsearch#search",
  "url": { "type": "application/json", "template": "..." },
  "queries": {
    "request":  [{ "searchTerms": "...", "count": 10, "startIndex": 1, "totalResults": "..." }],
    "nextPage": [{ "startIndex": 11, "count": 10 }]
  },
  "context": { "title": "SpecStream" },
  "searchInformation": {
    "searchTime": 0.0, "formattedSearchTime": "...",
    "totalResults": "...", "formattedTotalResults": "..."
  },
  "items": [{
    "kind": "customsearch#result",
    "title": "...", "htmlTitle": "...",
    "link": "...", "displayLink": "...",
    "snippet": "...", "htmlSnippet": "...",
    "formattedUrl": "...", "htmlFormattedUrl": "..."
  }]
}

queries.previousPage appears from the second page on. items is left out of a reply with no results, as on Google. pagemap and cacheId are not returned. What SpecStream returns beyond Google's fields is under specstream, on the reply and on each item. An error has Google's shape: {"error": {"code", "message", "errors", "status"}}.

$5 per 1,000 searches and the best scores published

A call of up to 10 results is $0.005, with no daily limit, and a 429 with Retry-After charges nothing. SpecStream scores 97.9 F-score on all 1,000 SimpleQA Verified questions (978 correct) and 64.0 item F1 and 43.4 row F1 on all 200 WideSearch tasks. On production on November 9, 2026, the median call took 0.82 s at 1 search a second and 1.07 s at 20 a second, and 718 of 720 calls were answered.

What is kept from a search

Nothing, on a key with zero retention: no request text and no answer after the reply. It is one field on the key, zero_retention, at the same price.

The same key reads pages and returns rows

The Extract API reads up to 20 pages or documents a call at $0.80 per 1,000 pages and scores 0.908 F1 on WCXB. Deep Search returns every match for a request in plain words as structured rows at 5¢, 15¢ or $1 a row, and quotes the most a run can cost before it starts.

Vertex AI Search

Google's suggestion for searching up to 50 domains, at $1.50 per 1,000 queries on Search Standard Edition. Its request is a POST to discoveryengine.googleapis.com with its own body and reply, so these examples are rewritten for it. SpecStream runs them as written, on the whole web.

Grounding with Google Search in the Gemini API

A Gemini model searches and writes an answer grounded in the results, at $14 per 1,000 search requests on Gemini 3 and newer after 5,000 free a month. Your code gets the model's answer. SpecStream returns items[] at $5 per 1,000.

Brave Search API

A search API on Brave's own index at $5 per 1,000 requests, with $5 in free credits every month and 50 queries per second. Its guide describes the move as swapping the endpoint and updating how you read the response. On SpecStream the code that reads Google's response stays.