Search API

The Search API combines web search functionality with content scraping capabilities. Search for any query and optionally scrape the full content from each search result in a single API call.

Authentication

Authorization

string

required

Bearer token using your API key: Bearer YOUR_API_KEY

Request Body

query

string

required

The search query string (1-500 characters)

limit

number

default:"10"

Maximum number of search results to return (1-20)

country

string

ISO country code for localized search results (e.g., “US”, “GB”, “JP”)

language

string

Language code for search results (e.g., “en”, “es”, “fr”)

provider

string

Search provider to use:

google - Google Search (default)
ollama - Alternative search provider

scrapeResults

boolean

default:"false"

Whether to scrape full content from each search result (+1 credit per result)

scrapeOptions

object

Configuration for scraping search results (only applies if scrapeResults=true)

Show scrapeOptions properties

scrapeOptions.format

string

default:"markdown"

Output format for scraped content:

markdown - Clean markdown format
html - HTML content
text - Plain text only
json - Structured JSON
structured - AI-enhanced structured data

scrapeOptions.includeScreenshot

boolean

default:"false"

Capture screenshot of each search result page

scrapeOptions.mobile

boolean

default:"false"

Use mobile viewport when scraping

scrapeOptions.extractionSchema

object

JSON schema for AI-powered data extraction from search results

scrapeOptions.maxAge

number

default:"30"

Cache max age in days (1-365)

Response

success

boolean

Indicates if the request was successful

data

object

Show data properties

query

string

The search query that was executed

results

array

Array of search results

Show result properties

position

number

Position in search results (1-based)

title

string

Search result title

link

string

URL of the search result

snippet

string

Search result snippet/description

displayLink

string

Display URL shown in search results

sitelinks

array

Additional sitelinks from the search result

content

string

Full scraped content in markdown format (only if scrapeResults=true)This field contains the complete scraped content. For markdown format, this includes all headings, paragraphs, lists, code blocks, and other structured elements.

markdown

string

Alias for content field (Firecrawl compatibility)Contains the same markdown content as the content field. Provided for compatibility with Firecrawl API format.

preview

string

Content preview snippet (first 200-250 characters)A quick preview of the content for scanning without reading the full text. Automatically generated from the scraped markdown content with formatting removed. Perfect for displaying in search results or dashboards.Example: “This article discusses best practices for web scraping, including rate limiting, respecting robots.txt, and using appropriate user agents…”

summary

string

Auto-generated content summary (200-300 characters)A concise summary extracted from the first few sentences of the content. Provides key information at a glance without reading the full article.Example: “Web scraping best practices include rate limiting to avoid overloading servers, respecting robots.txt directives, and using descriptive user agents. Implementing proper error handling and retry logic ensures reliability.”

scrapedAt

string

ISO timestamp when content was scrapedExample: “2025-01-15T14:32:10.123Z”

scrapeStatus

string

Status of scraping: success or failedIndicates whether content extraction was successful. If failed, check scrapeError for details.

scrapeError

string

Error message if scraping failedContains the error message if scrapeStatus is failed. Common errors include timeouts, blocked requests, or invalid URLs.

wordCount

number

Word count of scraped contentTotal number of words in the scraped content. Useful for estimating content length and quality.Example: 1250 (approximately 1,250 words)

readingTime

number

Estimated reading time in minutesCalculated based on average reading speed of 225 words per minute. Rounded up to at least 1 minute.Example: 6 (approximately 6 minutes to read)

metadata

object

Additional metadata about the scraped content

Show metadata properties

statusCode

number

HTTP status code from scraping requestExample: 200 (success), 404 (not found), 0 (scraping failed)

error

string

Error details if scraping failedContains technical error information for debugging purposes.

contentQuality

string

Assessed content quality: high, medium, or lowQuality assessment based on word count and content structure:

High: 500+ words with headings/lists/code blocks, OR 1000+ words
Medium: 200-500 words with some structure, OR 500-1000 words
Low: Less than 200 words or minimal structure

Helps filter and prioritize search results based on content depth.

totalResults

number

Estimated total number of search results available

searchTime

number

Time taken for search in seconds

creditsUsed

number

Total credits consumed (1 for search + 1 per scraped result)

metadata

object

Additional search metadata

Examples

Basic Search (No Scraping)

curl -X POST "https://api.whizo.ai/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best web scraping tools 2025",
    "limit": 10,
    "country": "US"
  }'

{
  "success": true,
  "data": {
    "query": "best web scraping tools 2025",
    "results": [
      {
        "position": 1,
        "title": "Top 10 Web Scraping Tools in 2025",
        "link": "https://example.com/scraping-tools",
        "snippet": "Comprehensive guide to the best web scraping tools available in 2025...",
        "displayLink": "example.com"
      },
      {
        "position": 2,
        "title": "Web Scraping Tools Comparison",
        "link": "https://another-site.com/comparison",
        "snippet": "Compare features, pricing, and capabilities of top web scraping platforms...",
        "displayLink": "another-site.com"
      }
    ],
    "totalResults": 45600,
    "searchTime": 0.42,
    "creditsUsed": 1
  }
}

Search with Content Scraping

curl -X POST "https://api.whizo.ai/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "web scraping best practices",
    "limit": 5,
    "scrapeResults": true,
    "scrapeOptions": {
      "format": "markdown",
      "includeScreenshot": false,
      "maxAge": 7
    }
  }'

{
  "success": true,
  "data": {
    "query": "web scraping best practices",
    "results": [
      {
        "position": 1,
        "title": "Web Scraping Best Practices Guide",
        "url": "https://example.com/best-practices",
        "description": "Learn the essential best practices for ethical and effective web scraping...",
        "displayLink": "example.com",
        "markdown": "# Web Scraping Best Practices\n\n## Introduction\nWeb scraping is a powerful technique for extracting data from websites. However, it must be done responsibly to respect website resources and legal boundaries.\n\n## Key Principles\n\n1. **Respect robots.txt** - Always check and follow robots.txt directives\n2. **Use rate limiting** - Avoid overwhelming servers with too many requests\n3. **Identify yourself** - Use descriptive user agents\n4. **Handle errors gracefully** - Implement retry logic with exponential backoff\n5. **Cache responses** - Minimize duplicate requests\n\n## Technical Implementation\n\nWhen implementing web scrapers, consider...",
        "content": "# Web Scraping Best Practices\n\n## Introduction\nWeb scraping is a powerful technique for extracting data from websites. However, it must be done responsibly to respect website resources and legal boundaries.\n\n## Key Principles\n\n1. **Respect robots.txt** - Always check and follow robots.txt directives\n2. **Use rate limiting** - Avoid overwhelming servers with too many requests\n3. **Identify yourself** - Use descriptive user agents\n4. **Handle errors gracefully** - Implement retry logic with exponential backoff\n5. **Cache responses** - Minimize duplicate requests\n\n## Technical Implementation\n\nWhen implementing web scrapers, consider...",
        "preview": "Web scraping is a powerful technique for extracting data from websites. However, it must be done responsibly to respect website resources and legal boundaries. Key principles include respecting robots.txt directives, using rate...",
        "summary": "Web scraping is a powerful technique for extracting data from websites. However, it must be done responsibly to respect website resources and legal boundaries. Always check and follow robots.txt directives, use rate limiting to avoid overwhelming servers, and identify yourself with descriptive user agents.",
        "scrapedAt": "2025-01-15T10:30:00Z",
        "scrapeStatus": "success",
        "wordCount": 1542,
        "readingTime": 7,
        "metadata": {
          "statusCode": 200,
          "contentQuality": "high"
        }
      },
      {
        "position": 2,
        "title": "Ethical Web Scraping Guidelines",
        "url": "https://another.com/ethics",
        "description": "Guidelines for responsible web scraping practices...",
        "displayLink": "another.com",
        "markdown": "# Ethical Web Scraping\n\nWhen scraping websites, it's crucial to follow ethical guidelines that protect both the scraper and the website owner. This includes respecting terms of service, avoiding personal data collection without consent, and being transparent about your scraping activities.",
        "content": "# Ethical Web Scraping\n\nWhen scraping websites, it's crucial to follow ethical guidelines that protect both the scraper and the website owner. This includes respecting terms of service, avoiding personal data collection without consent, and being transparent about your scraping activities.",
        "preview": "When scraping websites, it's crucial to follow ethical guidelines that protect both the scraper and the website owner. This includes respecting terms of service, avoiding personal data collection without consent, and being...",
        "summary": "When scraping websites, it's crucial to follow ethical guidelines that protect both the scraper and the website owner. This includes respecting terms of service, avoiding personal data collection without consent, and being transparent about your scraping activities.",
        "scrapedAt": "2025-01-15T10:30:05Z",
        "scrapeStatus": "success",
        "wordCount": 987,
        "readingTime": 5,
        "metadata": {
          "statusCode": 200,
          "contentQuality": "high"
        }
      }
    ],
    "totalResults": 12400,
    "searchTime": 8.5,
    "creditsUsed": 6
  }
}

Search with AI Extraction

curl -X POST "https://api.whizo.ai/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "top SaaS companies 2025",
    "limit": 10,
    "scrapeResults": true,
    "scrapeOptions": {
      "format": "structured",
      "extractionSchema": {
        "companyName": "string",
        "revenue": "string",
        "employees": "number",
        "founded": "number",
        "description": "string"
      }
    }
  }'

Error Responses

error

object

Show error properties

code

string

Error code identifier

message

string

Human-readable error message

details

object

Additional error context

Common Errors

Status Code	Error Code	Description
400	`invalid_query`	Search query is invalid or empty
400	`invalid_limit`	Limit must be between 1 and 20
401	`unauthorized`	Invalid or missing API key
402	`insufficient_credits`	Not enough credits for search and scraping
429	`rate_limited`	Rate limit exceeded
500	`search_failed`	Search provider returned an error
500	`scraping_failed`	Failed to scrape one or more results

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. Required: 11, Available: 5",
    "details": {
      "required": 11,
      "available": 5
    }
  }
}

Credit Costs

Operation	Cost
Search (without scraping)	1 credit
Search with scraping	1 credit + 1 credit per result
Search with scraping + screenshots	1 credit + 2 credits per result

Examples:

Search only (10 results): 1 credit
Search + scrape 5 results: 1 + 5 = 6 credits
Search + scrape 10 results with screenshots: 1 + (10 × 2) = 21 credits

Rate Limits

Rate limits vary by plan:

Free: 10 requests per hour, 100 per day
Starter: 50 requests per hour, 500 per day
Pro: 200 requests per hour, 2000 per day
Enterprise: Custom limits

Use Cases

Market Research

Search for competitors and automatically scrape their content for analysis:

{
  "query": "competitors in AI web scraping market",
  "limit": 20,
  "scrapeResults": true,
  "scrapeOptions": { "format": "markdown" }
}

Content Discovery

Find relevant articles and extract key information:

{
  "query": "latest AI trends 2025",
  "limit": 10,
  "scrapeResults": true,
  "scrapeOptions": {
    "format": "structured",
    "extractionSchema": {
      "title": "string",
      "summary": "string",
      "keyPoints": "array",
      "publishDate": "string"
    }
  }
}

Lead Generation

Search for potential customers and extract contact information:

{
  "query": "SaaS companies looking for web scraping solutions",
  "limit": 15,
  "scrapeResults": true,
  "scrapeOptions": {
    "extractionSchema": {
      "companyName": "string",
      "email": "string",
      "phone": "string",
      "website": "string"
    }
  }
}

Best Practices

Start without scraping to preview results before consuming credits
Use appropriate limit to balance cost and comprehensiveness
Enable caching with maxAge to avoid re-scraping recent results
Handle partial failures - some results may scrape successfully while others fail
Implement pagination for large result sets by adjusting limit
Use country/language parameters for localized results
Monitor credit usage especially when scraping many results

Scrape API - Scrape individual URLs
Crawl API - Crawl entire websites
Extract API - AI-powered data extraction
Map API - Discover website URLs

Core APIs

Job Management

User Management

Advanced Features

Authentication

Request Body

Response

Examples

Basic Search (No Scraping)

Search with Content Scraping

Search with AI Extraction

Error Responses

Common Errors

Credit Costs

Rate Limits

Use Cases

Market Research

Content Discovery

Lead Generation

Best Practices

Core APIs

Job Management

User Management

Advanced Features

​Authentication

​Request Body

​Response

​Examples

​Basic Search (No Scraping)

​Search with Content Scraping

​Search with AI Extraction

​Error Responses

​Common Errors

​Credit Costs

​Rate Limits

​Use Cases

​Market Research

​Content Discovery

​Lead Generation

​Best Practices

​Related Endpoints

Authentication

Request Body

Response

Examples

Basic Search (No Scraping)

Search with Content Scraping

Search with AI Extraction

Error Responses

Common Errors

Credit Costs

Rate Limits

Use Cases

Market Research

Content Discovery

Lead Generation

Best Practices

Related Endpoints