> ## 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.

# Search

> AI-powered web search with structured data extraction

## 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.

<Note>
  Try Search instantly in our [interactive playground](https://scrapegraphai.com/dashboard).
</Note>

## 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](https://scrapegraphai.com/pricing) for the full breakdown.

## Getting Started

### Quick Start

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```javascript JavaScript theme={null}
  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}`);
    }
  }
  ```

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

#### 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](/services/scrape#fetchconfig)).                                                                                                                                                                                                                                                                                                                    |

<Note>
  Get your API key from the [dashboard](https://scrapegraphai.com/dashboard).
</Note>

## Search + Extraction

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```javascript JavaScript theme={null}
  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);
  }
  ```

  ```bash cURL theme={null}
  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"}}
        }
      }
    }'
  ```
</CodeGroup>

#### Using a Pydantic schema (Python)

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

```python theme={null}
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)

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="AI-Powered Search" icon="brain">
    Search + content extraction in one call.
  </Card>

  <Card title="Structured Output" icon="table">
    Add a prompt and schema for typed JSON.
  </Card>

  <Card title="Localized Results" icon="globe">
    Use `locationGeoCode` for country-specific results.
  </Card>

  <Card title="Time Filters" icon="clock">
    Narrow to the past hour, day, week, month, or year.
  </Card>
</CardGroup>

## Integration Options

### Official SDKs

* [Python SDK](/sdks/python)
* [JavaScript SDK](/sdks/javascript) (`scrapegraph-js` ≥ 2.1.0, Node ≥ 22)

### AI Framework Integrations

* [LangChain Integration](/integrations/langchain)
* [LlamaIndex Integration](/integrations/llamaindex)

## Support & Resources

<CardGroup cols={2}>
  <Card title="Documentation" icon="book" href="/introduction">
    Guides and tutorials
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Detailed API documentation
  </Card>

  <Card title="Community" icon="discord" href="https://discord.gg/uJN7TYcpNa">
    Join our Discord community
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/ScrapeGraphAI">
    Check out our open-source projects
  </Card>
</CardGroup>