Introduction

Searlo is a fast, developer-friendly search API. Web, image, news, video, shopping and advanced search plus email verification — all with a single API key.

Base URL

https://api.searlo.tech/api/v1

Features

•Web Search — Ranked web results with snippets
•Image / Video / News Search — Media and real-time news results
•Site & Advanced Search — Site-restricted and filtered queries (date, file type, exact/exclude terms)
•Shopping Search — Product results
•Batch Search — Up to 10 queries in one request
•Suggestions & Trending — Autocomplete and trending queries
•Email Verifier — Validate email deliverability
•Search Analytics — Your own usage analytics
•MCP Server — Connect AI agents (Claude, Cursor, VS Code, Windsurf)
•Simple Auth — One API key, no OAuth complexity

Web Search

Search the web and get ranked results with titles, URLs, and snippets.

Endpoint

GET /search/web

> GET /search is an alias for /search/web (it accepts q, limit, page, gl, hl only — no safe/lr).

Credits: 1 per request

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 chars)
`limit`	number	No	Results per page (1–10, default: 10)
`page`	number	No	Page number (default: 1)
`safe`	string	No	Safe search: `active` or `off`
`lr`	string	No	Language restriction, max 50 chars (e.g. `lang_en`)
`gl`	string	No	Country code, max 5 chars (e.g. `us`, `gb`)
`hl`	string	No	Interface language code, max 5 chars (e.g. `en`)

Response

{
  "success": true,
  "searchInformation": {
    "totalResults": "1250000",
    "searchTime": 0.42,
    "query": "machine learning",
    "currentPage": 1,
    "hasNextPage": true
  },
  "items": [
    {
      "rank": 1,
      "title": "Introduction to Machine Learning",
      "link": "https://example.com/ml-intro",
      "snippet": "Machine learning is a subset of AI...",
      "domain": "example.com",
      "displayLink": "example.com"
    }
  ]
}

Responses also set X-Cache (HIT/MISS) and credit headers (X-Credits-Deducted, X-Credits-Remaining).

Image Search

Search for images with thumbnails and source URLs.

Endpoint

GET /search/images

Credits: 1 per request

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 chars)
`limit`	number	No	Results per page (1–10, default: 10)
`page`	number	No	Page number (default: 1)
`size`	string	No	One of `small`, `medium`, `large`, `xlarge`
`gl`	string	No	Country code, max 5 chars (e.g. `us`)
`hl`	string	No	Interface language code, max 5 chars (e.g. `en`)

Response

{
  "success": true,
  "searchInformation": {
    "totalResults": "50000",
    "searchTime": 0.35,
    "query": "sunset"
  },
  "items": [
    {
      "rank": 1,
      "title": "Beautiful Sunset",
      "link": "https://example.com/sunset.jpg",
      "type": "image",
      "image": {
        "src": "https://example.com/sunset.jpg",
        "thumbnail": "https://example.com/thumb.jpg",
        "width": 1920,
        "height": 1080,
        "contextLink": "https://example.com/gallery"
      }
    }
  ]
}

News Search

Search news articles from thousands of sources worldwide.

Endpoint

GET /search/news

Credits: 1 per request

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 chars)
`limit`	number	No	Results per page (1–10, default: 10)
`page`	number	No	Page number (default: 1)
`gl`	string	No	Country code, max 5 chars (e.g. `us`)
`hl`	string	No	Interface language code, max 5 chars (e.g. `en`)

> Note: Date filtering is not available on the news endpoint. For time-bounded results use Advanced Search with the dateRange parameter.

Response

{
  "success": true,
  "searchInformation": {
    "totalResults": "12500",
    "searchTime": 0.28,
    "query": "technology"
  },
  "items": [
    {
      "rank": 1,
      "title": "Tech News Article",
      "link": "https://news.example.com/article",
      "snippet": "Article summary...",
      "type": "news",
      "news": {
        "source": "Example News",
        "publishedDate": "2024-01-15T10:30:00Z",
        "author": "John Doe"
      }
    }
  ]
}

Video Search

Search for videos across the web.

Endpoint

GET /search/videos

Credits: 1 per request

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 chars)
`limit`	number	No	Results per page (1–10, default: 10)
`page`	number	No	Page number (default: 1)
`safe`	string	No	Safe search: `active` or `off`
`gl`	string	No	Country code, max 5 chars (e.g. `us`)
`hl`	string	No	Interface language code, max 5 chars (e.g. `en`)

Response

Same enhanced envelope as Web Search (searchInformation + items), with video metadata per item.

{
  "success": true,
  "searchInformation": { "query": "react tutorial" },
  "items": [
    {
      "rank": 1,
      "title": "React Tutorial for Beginners",
      "link": "https://video.example.com/watch?v=abc",
      "snippet": "Learn React in 1 hour...",
      "type": "video"
    }
  ]
}

Site Search

Restrict a web search to a single site or domain.

Endpoint

GET /search/site

Credits: 1 per request

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 chars)
`site`	string	Yes	Domain or URL (e.g. `example.com` or `https://example.com`)
`limit`	number	No	Results per page (1–10, default: 10)
`page`	number	No	Page number (default: 1)

Response

Same enhanced envelope as Web Search (searchInformation + items), scoped to the given site.

Advanced Search

Run complex queries with filters: date range, file type, exact phrases, excluded terms and site restriction. Available as GET (query params) or POST (JSON body).

Endpoint

GET  /search/advanced
POST /search/advanced

Credits: 1 per request

Parameters

Provide the query as either query or q (one is required).

Parameter	Type	Required	Description
`query` / `q`	string	Yes	Search query (1–500 chars)
`limit`	number	No	Results (1–10, default: 10)
`dateRange`	string	No	One of `day`, `week`, `month`, `year`
`timeRange`	string	No	Alias of `dateRange` (`day`/`week`/`month`/`year`)
`fileType`	string	No	File type filter, max 20 chars (e.g. `pdf`)
`exactTerms`	string	No	Exact phrase to include, max 200 chars
`excludeTerms`	string	No	Terms to exclude, max 200 chars
`site`	string	No	Restrict to a domain/URL (e.g. `example.com`)

Response

Same enhanced envelope as Web Search (searchInformation + items).

Shopping Search

Search product/shopping results.

Endpoint

GET /search/shopping

Credits: 1 per request

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 chars)
`limit`	number	No	Results (1–55, default: 55)
`gl`	string	No	Country code, max 5 chars (e.g. `us`)
`hl`	string	No	Interface language code, max 5 chars (e.g. `en`)

Response

{
  "success": true,
  "searchParameters": { "q": "wireless earbuds", "type": "shopping", "gl": "us", "hl": "en" },
  "shopping": [
    { "title": "Wireless Earbuds Pro", "price": "$79.99", "source": "example-store.com", "link": "https://..." }
  ],
  "source": "searlo.tech(google)"
}

If no products are found you get a 200 with "shopping": []. If upstream is temporarily blocked you get a 503 with "retryable": true.

Simple Search

Legacy web search that returns a simplified, flat result format. Use Web Search for new integrations.

Endpoint

GET /search/simple

Credits: 1 per request

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query (1–500 chars)
`limit`	number	No	Results (1–10, default: 10)

Response

{
  "success": true,
  "data": { "results": [ { "title": "...", "link": "...", "snippet": "..." } ] },
  "message": "Simple search completed successfully"
}

Suggestions & Trending

Autocomplete suggestions and trending queries.

Credit Cost

•Autocomplete (/search/suggestions): 0.5 credits per request
•Trending (/search/trending): Free (0 credits)

Autocomplete Endpoint

GET /search/suggestions

Parameter	Type	Required	Description
`q`	string	Yes	Partial query (1–200 chars)
`limit`	number	No	Number of suggestions (1–10, default: 10)
`hl`	string	No	Language code (2–5 chars, default: `en`)

{
  "success": true,
  "data": ["machine learning", "machine learning python", "machine learning course"],
  "message": "Suggestions retrieved successfully"
}

Trending Endpoint

GET /search/trending

Parameter	Type	Required	Description
`region`	string	No	2-letter country code, uppercase (default: `US`)

{
  "success": true,
  "data": ["trending topic 1", "trending topic 2"],
  "message": "Trending searches retrieved successfully"
}

Batch Search

Run multiple web searches in a single request.

Endpoint

POST /search/batch

Credits: 1 credit per query in the batch (e.g. 4 queries = 4 credits, capped at 10).

Body

Field	Type	Required	Description
`queries`	string[]	Yes	1–10 query strings (each 1–500 chars)

Response

{
  "success": true,
  "data": [
    { "query": "react", "items": [ /* ... */ ] },
    { "query": "vue", "items": [ /* ... */ ] }
  ],
  "message": "Batch search completed successfully"
}

Search Analytics

Retrieve analytics about your own search usage. Free (0 credits).

Endpoint

GET /search/analytics

Parameters

Parameter	Type	Required	Description
`startDate`	string	No	ISO date — filter from this date
`endDate`	string	No	ISO date — filter up to this date (must be after `startDate`)
`searchType`	string	No	Filter by type (e.g. `web`, `image`, `news`, `batch`)

Response

{
  "success": true,
  "data": {
    "totalSearches": 1284,
    "searchesByType": { "web": 900, "image": 200, "news": 184 },
    "recentSearches": [ { "query": "...", "searchType": "web", "createdAt": "..." } ],
    "popularQueries": [ { "query": "react", "count": 42 } ],
    "creditsUsed": 1284,
    "averageResponseTime": 412
  },
  "message": "Analytics retrieved successfully"
}

Email Verifier

Validate an email address's deliverability.

Verify Endpoint

POST /email-verifier/verify

Credits: 5 per request. Rate-limited by the separate email_verifier tier group (see Rate Limiting).

Body

Field	Type	Required	Description
`email`	string	Yes	Email address to verify

Response

Responses use the standard envelope (statusCode, success, message, data).

{
  "statusCode": 200,
  "success": true,
  "message": "Email verified",
  "data": {
    "email": "[email protected]",
    "status": "valid",
    "domain": "example.com",
    "message": "Mailbox exists",
    "details": {
      "format": true,
      "mailboxStatus": "...",
      "mailboxType": "...",
      "mailboxExchange": "..."
    },
    "verifiedAt": "2026-05-20T10:30:00.000Z",
    "source": "searlo"
  }
}

status is one of: valid, invalid, accept_all, unknown, error.

History Endpoint

GET /email-verifier/history

Credits: Free (0). Returns your past verifications, paginated.

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (1–100, default: 20)

Rate Limiting

API requests are rate-limited per user with sliding windows. Limits scale automatically with your tier — the more credits you purchase, the higher your tier.

Limits are tracked per endpoint group: search (all /search/*), email_verifier (email verification), and mcp (MCP server). Each group has its own independent buckets.

Tier Thresholds

Your tier is set by total credits ever purchased:

Tier	Min. credits purchased
Free	0
Micro	1
Starter	5,001
Builder	20,001
Scale	75,001
Pro	250,001
Enterprise	900,001

Search Limits (`/search/*`)

Tier	Per Second	Per Minute	Per Hour	Per Day
Free	5	10	200	1,000
Micro	7	20	400	2,500
Starter	10	40	750	5,000
Builder	14	75	1,500	10,000
Scale	18	150	3,000	25,000
Pro	24	300	6,000	60,000
Enterprise	30	600	15,000	150,000

Email Verifier Limits (`/email-verifier/*`)

Tier	Per Second	Per Minute	Per Hour	Per Day
Free	1	5	50	200
Micro	1	8	80	400
Starter	2	15	150	800
Builder	3	25	300	1,500
Scale	4	40	500	3,000
Pro	5	60	800	5,000
Enterprise	8	100	1,500	10,000

MCP Limits (`/mcp`)

Tier	Per Second	Per Minute	Per Hour	Per Day
Free	5	10	150	750
Micro	7	20	300	1,500
Starter	10	40	600	3,000
Builder	14	75	1,000	6,000
Scale	18	150	2,000	12,500
Pro	24	300	4,000	30,000
Enterprise	30	600	8,000	75,000

> Tip: Your tier upgrades automatically based on total credits purchased.

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

Handling Rate Limits

A 429 Too Many Requests response:

{
  "success": false,
  "message": "Too many requests. Please slow down.",
  "retryAfter": 60
}

Error Handling

All errors return a consistent JSON format.

Error Response Format

{
  "success": false,
  "message": "Error description",
  "error": "Technical error details (optional)"
}

Validation errors include an errors array of { field, message }:

{
  "success": false,
  "message": "Query validation failed: Search query is required",
  "errors": [{ "field": "q", "message": "Search query is required" }]
}

Insufficient-credit errors (402) include a machine-readable code and details:

{
  "success": false,
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "details": { "required": 5, "available": 2, "shortfall": 3 },
  "message": "This request requires 5 credit(s), but you only have 2 credit(s) available."
}

HTTP Status Codes

Status	Meaning
400	Bad Request — invalid parameters or validation error
401	Unauthorized — invalid or missing API key
402	Payment Required — insufficient credits (`code: INSUFFICIENT_CREDITS`)
403	Forbidden — account disabled or removed
404	Not Found — route or user not found
429	Too Many Requests — rate limit exceeded
500	Server Error — something went wrong
503	Service Unavailable — warming up / temporarily unavailable (`retryable: true`)

Retryable Errors

502/503 responses include "retryable": true and may include an errorCode (e.g. WARMING). Wait briefly (respect Retry-After when present) and retry.

Common Error Messages

Message	Cause	Solution
Search query is required	Missing `q` parameter	Add `?q=...` to the URL
Invalid or expired API key	Bad API key	Check the `x-api-key` header
Insufficient credits	Out of credits	Top up your account
Too many requests	Rate limit hit	Wait and retry
Route Not Found	Invalid endpoint	Check the endpoint URL

MCP Server

Connect AI agents like Claude, Cursor, VS Code Copilot, and Windsurf to Searlo via Model Context Protocol (MCP).

Endpoint

https://api.searlo.tech/api/v1/mcp

Transport

Streamable HTTP — the latest MCP specification. No stdio, no Docker, no proxy needed.

Authentication

Use your API key in the X-API-Key header. The same key works for both MCP and the REST API.

Available Tools

Tool	Credits	Description
`web_search`	1	Google web search — organic results, knowledge panels, SERP features
`check_balance`	0	Current credit balance and low-balance status
`get_usage_stats`	0	Credit usage statistics for a time period
`get_search_history`	0	Your past searches
`get_search_stats`	0	Search analytics: timeline, top queries, type distribution
`get_transaction_history`	0	Credit transaction history
`list_api_keys`	0	Your API keys with masked previews

web_search Parameters

Parameter	Type	Required	Description
`query`	string	Yes	The search query (1–2048 chars)
`num`	number	No	Results count (1–10, default: 10)
`page`	number	No	Page number (default: 1)
`gl`	string	No	Country code, 2 letters (us, gb, de…)
`lr`	string	No	Language restriction (en, fr, de…)
`safe`	string	No	Safe search: `off`, `medium`, `high`	`format`	string	No	`toon` (default, ~63% fewer tokens), `json`, or `enhanced`

Other Tool Parameters

•get_usage_stats: days (1–365, default 30)
•get_search_history: limit (1–50, default 10), page (default 1), searchType (web/image/news)
•get_search_stats: startDate (ISO), endDate (ISO), groupBy (hour/day/week/month)
•get_transaction_history: limit (1–50, default 10), page (default 1), type (deduction/grant/refund/purchase)
•check_balance, list_api_keys: no parameters

Quick Setup

Paste the config into your AI client's MCP settings file and replace sk_your_api_key with your key.

Introduction

Base URL

Features

Quick Start

1. Get Your API Key

2. Make Your First Request

Authentication

Getting Your API Key

Using Your API Key

Web Search

Endpoint

Parameters

Response

Image Search

Endpoint

Parameters

Response

News Search

Endpoint

Parameters

Response

Video Search

Endpoint

Parameters

Response

Site Search

Endpoint

Parameters

Response

Advanced Search

Endpoint

Parameters

Response

Shopping Search

Endpoint

Parameters

Response

Simple Search

Endpoint

Parameters

Response

Suggestions & Trending

Credit Cost

Autocomplete Endpoint

Trending Endpoint

Batch Search

Endpoint

Body

Response

Search Analytics

Endpoint

Parameters

Response

Email Verifier

Verify Endpoint

Body

Response

History Endpoint

Rate Limiting

Tier Thresholds

Search Limits (/search/*)

Email Verifier Limits (/email-verifier/*)

MCP Limits (/mcp)

Rate Limit Headers

Handling Rate Limits

Error Handling

Error Response Format

HTTP Status Codes

Retryable Errors

Common Error Messages

MCP Server

Endpoint

Transport

Authentication

Available Tools

web_search Parameters

Other Tool Parameters

Quick Setup

Search Limits (`/search/*`)

Email Verifier Limits (`/email-verifier/*`)

MCP Limits (`/mcp`)