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

> Run a web search and fetch the top results in one call.

```http theme={null}
POST https://v2-api.scrapegraphai.com/api/search
```

Replaces the v1 `searchscraper` endpoint. Returns the top pages with their content inline, and optionally runs an AI extraction across all results.

## Request body

<ParamField body="query" type="string" required>
  The search query.
</ParamField>

<ParamField body="numResults" type="integer">
  Number of results to return and fetch (1–20). Default: `3`.
</ParamField>

<ParamField body="prompt" type="string">
  Optional prompt for AI extraction across the fetched results. When provided, the response also includes a `json` field.
</ParamField>

<ParamField body="schema" type="object">
  JSON schema for the extracted output. Requires `prompt`.
</ParamField>

<ParamField body="format" type="string">
  Format used for each result's inline content: `"markdown"` (default) or `"html"`.
</ParamField>

<ParamField body="timeRange" type="string">
  Recency filter: `"past_hour"`, `"past_24_hours"`, `"past_week"`, `"past_month"`, `"past_year"`.
</ParamField>

<ParamField body="locationGeoCode" type="string">
  ISO 3166-1 alpha-2 country code for localized results (e.g. `"us"`, `"it"`).
</ParamField>

<ParamField body="fetchConfig" type="object">
  Fetch-time options applied when crawling each result. See the [Scrape endpoint](/api-reference/endpoint/scrape#request-body) for the full field list.
</ParamField>

## Example request

```bash 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": "scrapegraphai pricing",
    "numResults": 3
  }'
```

## Example response

```json theme={null}
{
  "id": "27783ace-462a-45d2-9ff1-cdf3a22adf87",
  "results": [
    {
      "url": "https://scrapegraphai.com/pricing",
      "title": "Pricing - ScrapeGraphAI",
      "content": "// Choose the plan that fits your needs\n\n## Simple, transparent pricing ..."
    }
  ],
  "metadata": {
    "search": {},
    "pages": {
      "requested": 3,
      "scraped": 3
    }
  }
}
```

| Field                                   | Description                                                           |
| --------------------------------------- | --------------------------------------------------------------------- |
| `id`                                    | UUID for this search call.                                            |
| `results[]`                             | Ordered list of fetched results.                                      |
| `results[].url` / `.title` / `.content` | Result URL, title, and inline page content in the requested `format`. |
| `metadata.pages.requested` / `.scraped` | Requested vs. successfully fetched count.                             |

## Search + extraction

Add `prompt` (and optionally `schema`) to roll all results into one structured payload:

```bash 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" } }
      }
    }
  }'
```

When a `prompt` is supplied, the response includes three extra fields alongside `results`:

```json theme={null}
{
  "id": "74fb4595-1a77-4d6a-8c93-60894913fb41",
  "results": [ /* fetched pages as above */ ],
  "json": { "tips": ["..."] },
  "raw": null,
  "usage": { "promptTokens": 8421, "completionTokens": 310 },
  "metadata": {
    "search": {},
    "pages": { "requested": 5, "scraped": 5 }
  }
}
```

| Field                                      | Description                                                                        |
| ------------------------------------------ | ---------------------------------------------------------------------------------- |
| `json`                                     | Structured output matching the schema (free-form JSON when no schema is supplied). |
| `raw`                                      | Raw model output before JSON parsing, when available.                              |
| `usage.promptTokens` / `.completionTokens` | LLM token accounting.                                                              |

## Related

* Service overview: [Search](/services/search)
* SDK wrappers: [Python](/sdks/python) · [JavaScript](/sdks/javascript)