Search

Overview

Search runs a web query and returns the top results with their content already fetched. Optionally add a prompt and schema to have the results summarised into structured JSON.

Try Search instantly in our interactive playground.

Pricing

Mode	Credits
Search without `prompt`	2 per result
Search with `prompt` (structured extraction)	5 per result

Enabling stealth in fetchConfig adds 5 credits; render mode (auto / fast / js) does not affect the cost. See the pricing page for the full breakdown.

Getting Started

Quick Start

from scrapegraph_py import ScrapeGraphAI

# reads SGAI_API_KEY from env, or pass explicitly: ScrapeGraphAI(api_key="...")
sgai = ScrapeGraphAI()

res = sgai.search(
    "best programming languages 2024",
    num_results=3,
)

if res.status == "success":
    for r in res.data.results:
        print(r.title, "-", r.url)
else:
    print("Failed:", res.error)

import { ScrapeGraphAI } from "scrapegraph-js";

const sgai = ScrapeGraphAI();

const res = await sgai.search({
  query: "best programming languages 2024",
  numResults: 3,
});

if (res.status === "success") {
  for (const r of res.data?.results ?? []) {
    console.log(`${r.title} - ${r.url}`);
  }
}

curl -X POST https://v2-api.scrapegraphai.com/api/search \
  -H "SGAI-APIKEY: $SGAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best programming languages 2024",
    "numResults": 3
  }'

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The search query.
`numResults` / `num_results`	int	No	Number of results (1–20). Default: `3`.
`prompt`	string	No	Prompt used for AI extraction across the fetched results.
`schema`	object	No	JSON schema for structured output (requires `prompt`). In Python you can pass a Pydantic model via `MyModel.model_json_schema()`.
`format`	string	No	Output format for page content: `"markdown"` (default) or `"html"`.
`mode`	string	No	HTML processing mode: `"normal"`, `"reader"`, or `"prune"`. Default: `"prune"` (different from Scrape/Extract, which default to `"normal"`).
`timeRange` / `time_range`	string	No	Recency filter: `"past_hour"`, `"past_24_hours"`, `"past_week"`, `"past_month"`, `"past_year"`.
`locationGeoCode` / `location_geo_code`	string	No	Two-letter ISO country code for localized results. Curated set (52): `ae`, `ar`, `at`, `au`, `be`, `br`, `ca`, `ch`, `cl`, `cn`, `co`, `cz`, `de`, `dk`, `eg`, `es`, `fi`, `fr`, `gb`, `gr`, `hk`, `hu`, `id`, `ie`, `il`, `in`, `it`, `jp`, `kr`, `mx`, `my`, `ng`, `nl`, `no`, `nz`, `pe`, `ph`, `pk`, `pl`, `pt`, `ro`, `ru`, `sa`, `se`, `sg`, `th`, `tr`, `tw`, `ua`, `us`, `vn`, `za`.
`fetchConfig` / `fetch_config`	object	No	Fetch options (see Scrape · FetchConfig).

Get your API key from the dashboard.

Search + Extraction

Combine search with AI extraction to roll results into one structured output.

from scrapegraph_py import ScrapeGraphAI

sgai = ScrapeGraphAI()

res = sgai.search(
    "best programming languages 2024",
    num_results=3,
    prompt="Summarize the top languages and why they are recommended",
    schema={
        "type": "object",
        "properties": {
            "languages": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "reason": {"type": "string"},
                    },
                },
            },
        },
    },
)

if res.status == "success":
    print(res.data.json_data)

import { ScrapeGraphAI } from "scrapegraph-js";

const sgai = ScrapeGraphAI();

const res = await sgai.search({
  query: "typescript best practices",
  numResults: 5,
  prompt: "Extract the main tips and recommendations",
  schema: {
    type: "object",
    properties: {
      tips: { type: "array", items: { type: "string" } },
    },
  },
});

if (res.status === "success") {
  console.log(res.data?.json);
}

curl -X POST https://v2-api.scrapegraphai.com/api/search \
  -H "SGAI-APIKEY: $SGAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript best practices",
    "numResults": 5,
    "prompt": "Extract the main tips and recommendations",
    "schema": {
      "type": "object",
      "properties": {
        "tips": {"type": "array", "items": {"type": "string"}}
      }
    }
  }'

Using a Pydantic schema (Python)

Reuse a Pydantic BaseModel as both the schema and the response parser:

from pydantic import BaseModel
from scrapegraph_py import ScrapeGraphAI

class Language(BaseModel):
    name: str
    reason: str

class TopLanguages(BaseModel):
    languages: list[Language]

sgai = ScrapeGraphAI()

res = sgai.search(
    "best programming languages 2025",
    num_results=3,
    prompt="Summarize the top languages and why each is recommended.",
    schema=TopLanguages.model_json_schema(),
)

if res.status == "success":
    parsed = TopLanguages.model_validate(res.data.json_data)
    for lang in parsed.languages:
        print(lang.name, "—", lang.reason)

Async Support (Python)

import asyncio
from scrapegraph_py import AsyncScrapeGraphAI

async def main():
    async with AsyncScrapeGraphAI() as sgai:
        res = await sgai.search(
            "Best practices for web scraping",
            num_results=5,
        )
        if res.status == "success":
            for r in res.data.results:
                print(r.title, "-", r.url)

asyncio.run(main())

Key Features

AI-Powered Search

Search + content extraction in one call.

Structured Output

Add a prompt and schema for typed JSON.

Localized Results

Use locationGeoCode for country-specific results.

Time Filters

Narrow to the past hour, day, week, month, or year.

Integration Options

Official SDKs

Python SDK
JavaScript SDK (scrapegraph-js ≥ 2.1.0, Node ≥ 22)

AI Framework Integrations

Support & Resources

Documentation

Guides and tutorials

API Reference

Detailed API documentation

Community

Join our Discord community

GitHub

Check out our open-source projects

Get Started

Services

Official SDKs

LLM SDKs

Frameworks

Personal AI Agents

No-code

Contribute

Overview

Pricing

Getting Started

Quick Start

Parameters

Search + Extraction

Using a Pydantic schema (Python)

Async Support (Python)

Key Features

AI-Powered Search

Structured Output

Localized Results

Time Filters

Integration Options

Official SDKs

AI Framework Integrations

Support & Resources

Documentation

API Reference

Community

GitHub

​Overview

​Pricing

​Getting Started

​Quick Start

​Parameters

​Search + Extraction

​Using a Pydantic schema (Python)

​Async Support (Python)

​Key Features

AI-Powered Search

Structured Output

Localized Results

Time Filters

​Integration Options

​Official SDKs

​AI Framework Integrations

​Support & Resources

Documentation

API Reference

Community

GitHub

Overview

Pricing

Getting Started

Quick Start

Parameters

Search + Extraction

Using a Pydantic schema (Python)

Async Support (Python)

Key Features

Integration Options

Official SDKs

AI Framework Integrations

Support & Resources