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

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.

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.