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`.
`allowedTypes` / `allowed_types`	array	No	Optional non-empty MIME allowlist. Omit it to allow every supported type, including PDF.
`processors`	array	No	Omit for the 25-page PDF cap. Send it only to override the cap; `maxPages` also defaults to 25 when omitted, and `-1` means unlimited. PDF processing costs 1 credit per page actually processed. Configure PDF page limits.
`fetchConfig` / `fetch_config`	object	No	Fetch options (see Scrape · FetchConfig).

Get your API key from the dashboard.

Content Types and PDF Processing

By default Search accepts every supported content type, including PDFs. Use allowedTypes to restrict which MIME types may be fetched, and configure the PDF page cap independently with processors. Excluding application/pdf rejects PDF results even when a PDF processor is present.

There is no special "all" or "*" value. To allow every supported type, omit allowedTypes entirely. The playground follows this rule in generated snippets: when “All types” is selected, it does not print the full MIME list. If allowedTypes is present, it must contain at least one exact MIME type and cannot contain duplicates.

res = sgai.search(
    "attention is all you need paper",
    num_results=5,
    allowed_types=["application/pdf"],
    processors=[{"type": "pdf", "max_pages": 10}],
)

const res = await sgai.search({
  query: "attention is all you need paper",
  numResults: 5,
  allowedTypes: ["application/pdf"],
  processors: [{ type: "pdf", maxPages: 10 }],
});

curl -X POST https://v2-api.scrapegraphai.com/api/search \
  -H "SGAI-APIKEY: $SGAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "attention is all you need paper",
    "numResults": 5,
    "allowedTypes": ["application/pdf"],
    "processors": [{"type": "pdf", "maxPages": 10}]
  }'

allowedTypes and processors must each be non-empty when provided. Set maxPages to -1 to process every PDF page.

The playground reserves an estimate based on numResults and the configured PDF page cap. PDF processing costs 1 credit per page actually processed; rejected or failed pages are not charged as successful results.

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

Content Types and PDF Processing

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

​Content Types and PDF Processing

​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

Content Types and PDF Processing

Search + Extraction

Using a Pydantic schema (Python)

Async Support (Python)

Key Features

Integration Options

Official SDKs

AI Framework Integrations

Support & Resources