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

array

Optional MIME allowlist for fetched results. Omit this field to allow every supported type, including application/pdf. There is no "all" or "*" keyword. When provided, it must be a non-empty array of exact supported MIME types, such as ["text/html", "application/pdf"]. Rejected types are reported as failed pages and do not appear in results.

array

Optional processing configuration. Omit this field to use the 25-page PDF cap. You may also send {"type":"pdf"} and omit maxPages; it defaults to 25. Set maxPages only to override the default, using 1–500, or -1 for no page limit. PDF processing costs 1 credit per page actually processed. See Configure PDF page limits for examples. This does not change allowedTypes.

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,
    "allowedTypes": ["text/html", "application/pdf"],
    "processors": [{"type": "pdf", "maxPages": 10}]
  }'

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