Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.scrapegraphai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ModeCredits
Search without prompt2 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)

​
Parameters

ParameterTypeRequiredDescription
querystringYesThe search query.
numResults / num_resultsintNoNumber of results (1–20). Default: 3.
promptstringNoPrompt used for AI extraction across the fetched results.
schemaobjectNoJSON schema for structured output (requires prompt). In Python you can pass a Pydantic model via MyModel.model_json_schema().
formatstringNoOutput format for page content: "markdown" (default) or "html".
modestringNoHTML processing mode: "normal", "reader", or "prune". Default: "prune" (different from Scrape/Extract, which default to "normal").
timeRange / time_rangestringNoRecency filter: "past_hour", "past_24_hours", "past_week", "past_month", "past_year".
locationGeoCode / location_geo_codestringNoTwo-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_configobjectNoFetch 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)

​
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

​
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