POST /v1/search — web search and scrape

POST /v1/search

Search the web. Optionally scrape every result in the same call. Five credits, plus one per scraped result.

Get your API keyCost · 5 credits + 1 per scraped result

Overview

What this verb does.

search issues a web query through a backend provider (DuckDuckGo HTML by default; SearchAPI/Serper as a v1.5 premium upgrade). It returns the top N results with title, URL and snippet.

Set scrape_results: true and Stekpad runs the scrape verb against each result and merges the markdown into the response. This is the verb most-used by Claude agents — it is the cheapest path to current web context inside an MCP call.

Request

Make the call.

Pick your language. Every snippet is a real, runnable example.

curl -X POST https://api.stekpad.com/v1/search \
  -H "Authorization: Bearer stkpd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best project management tools 2026",
    "num_results": 10,
    "scrape_results": true,
    "scrape_options": { "formats": ["markdown"] },
    "country": "US",
    "language": "en"
  }'

Parameters

Request body.

Name	Type	Required	Description
query	string	required	The search query.
num_results	int	optional	Default 10. Max 50.
scrape_results	boolean	optional	If true, runs scrape on each result.
scrape_options	object	optional	Same shape as /v1/scrape.
country	string	optional	ISO country code. Default US.
language	string	optional	ISO language code. Default en.
dataset	object	optional	Land results as rows in a table dataset.

Response

What you get back.

search-response.json

json

{
  "run_id": "run_01HZ...",
  "query": "best project management tools 2026",
  "results": [
    {
      "position": 1,
      "url": "https://example.com/best-pm-tools",
      "title": "The Best Project Management Tools of 2026",
      "snippet": "We tested 30 tools...",
      "scrape": { "markdown": "# The Best...\n..." }
    }
  ],
  "credits_charged": 15
}

Errors

Structured, typed, actionable.

Code	When
query_too_short	Query under 2 characters.
search_provider_unavailable	The backend search provider rate-limited us.
target_blocked	A specific result could not be scraped. The other results still return.

Every error includes a code, a human message, and a guidance field with the exact action to take.

The other four verbs.

scrape1 credit

Fetch one URL. Markdown, JSON, HTML or a screenshot.

POST /v1/scrape
{ "url": "https://example.com" }

crawl1 / page

Walk an entire site. Async, with webhooks and a run_id you can poll.

POST /v1/crawl
{ "url": "https://example.com" }

map1 / 1k URLs

Discover URLs without rendering pages. Walks sitemaps in seconds.

POST /v1/map
{ "url": "https://example.com" }

extract5 / URL

JSON Schema in, validated structured fields out.

POST /v1/extract
{ "urls": ["https://acme.com/about"], "schema": {...} }

Try /v1/search now.

Get an API key, paste the curl, watch the row land in your dataset.

Get your API key Read the docs