Search

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

string

required

The search query.

integer

Number of results to return and fetch (1–20). Default: 3.

string

Optional prompt for AI extraction across the fetched results. When provided, the response also includes a json field.

object

JSON schema for the extracted output. Requires prompt.

string

Format used for each result’s inline content: "markdown" (default) or "html".

string

Recency filter: "past_hour", "past_24_hours", "past_week", "past_month", "past_year".

string

ISO 3166-1 alpha-2 country code for localized results (e.g. "us", "it").

object

Fetch-time options applied when crawling each result. See the Scrape endpoint for the full field list.

Example request

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

{
  "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:

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:

{
  "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.

Service overview: Search
SDK wrappers: Python · JavaScript

API Documentation

Scrape

Extract

Crawl

Monitor

History

Account

Search

Request body

Example request

Example response

Search + extraction

​Request body

​Example request

​Example response

​Search + extraction

​Related

Request body

Example request

Example response

Search + extraction

Related