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
Agent and research jobs often need open-web discovery before they have a URL to fetch. Social platform search finds TikTok videos or Reddit posts; product docs, competitor landing pages, and blog posts still live on the ordinary web.
`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` (defaults to 1). 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. It defaults to 1 when omitted. There is no cursor field on this route — bump page for the next set of ranked results.
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.