Web Search API
Keyword search across the public web — query in, ranked title/URL/snippet rows out, same credit wallet as social and page-extract routes.
GET /v1/web/search1 credit per successful request.
About this endpoint
`GET /v1/web/search` takes a required `query` string and returns ranked organic results in the shared Social Fetch envelope. Each row has `title`, `url`, and a `content` snippet. Optional `region` (ISO 3166-1 country code such as `US` or `GB`) localizes results. Optional `datePosted` accepts `last-hour`, `last-day`, `last-week`, `last-month`, or `last-year`. Pagination uses 1-based `page` (default: 1); the response includes `data.page` with a best-effort `hasMore` / `nextPage` (upstream search does not report an exact total). Bill from `meta.creditsCharged`.
This route finds pages. To turn a known URL into markdown, HTML, or a Q&A answer, use `GET /v1/web/markdown`, `GET /v1/web/html`, or `GET /v1/web/ask`. For a small set of URLs in one call, use `GET /v1/web/crawl`. All of them share one Social Fetch API key.
Web Search API FAQ
What does the Web Search API return?
A data object with the executed query string and a results array. Each result has title, url, and content (a text snippet). The response uses the shared Social Fetch envelope with meta.requestId and meta.creditsCharged. An empty results array is a valid success when nothing matched.
How do I call web search?
Send GET /v1/web/search with x-api-key and a required query parameter (1–500 characters). Optionally add region, datePosted, and page. Full parameter enums and examples are in the API docs.
How much does web search cost?
Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth. Each paginated page is a separate billed request.
Is this the same as web markdown or ask?
No. GET /v1/web/search discovers public pages by keyword. GET /v1/web/markdown, GET /v1/web/html, and GET /v1/web/ask need a URL you already have. Typical flow: search for candidates, then extract or ask on the URLs you keep.
Can I filter web search by region or recency?
Yes. region takes an optional ISO 3166-1 country code (for example US, GB, CA). datePosted accepts last-hour, last-day, last-week, last-month, or last-year. Keep the same query and filters when you change page.
How does pagination work on web search?
Pass page as a 1-based page number (default: 1). Read data.page.hasMore and data.page.nextPage for continuation. hasMore is best-effort: the upstream provider reports no result total, so it is true when the page came back full.
Do I need a Google API key to search the web?
No. You authenticate to Social Fetch with an API key. The route returns public organic-style results; it does not use your Google Cloud project or Custom Search Engine credentials.