Search the web
Search the web. Two modes governed by ``scrapeOptions``.
- **Omit ``scrapeOptions``** → SERP-only: returns the search engine's raw
snippets (``url`` + ``meta`` with ``title`` / ``description`` /
``source`` / ``publishedAt`` / ``imageUrl*``). No per-page fetch, fast
and cheap.
- **Pass ``scrapeOptions: {}``** → deep-scrape every result, return
page-faithful Markdown under ``markdown``.
- **Pass ``scrapeOptions: {"format": "json"}``** → deep-scrape every
result, return the structured page summary under ``json`` (same shape as
``/webtools/scrape``'s ``json`` field).
In deep-scrape mode, results where the chosen format produced no content
are dropped from the response, so the response may hold fewer than
``limit`` results. ``meta.statusCode`` carries the fetched page's HTTP
status when deep-scraped.
``query`` is compatible with common Google search-operator syntax:
``site:``, ``intitle:``, ``filetype:``, ``"exact phrase"``, ``-exclude``.
To filter by whole domains, prefer the structured ``includeDomains`` /
``excludeDomains`` — they are folded into the matching ``site:`` /
``-site:`` operators (and may be combined, e.g. include a parent domain
while excluding one subdomain).
Use ``sources`` to pick the result bucket — ``"web"`` (default),
``"news"``, or ``"images"`` (combinable); ``tbs`` for a time filter
(``qdr:d`` / ``qdr:w`` / ``qdr:m`` / ``qdr:y``); ``limit`` (1-20, default
10) to cap results.
Billing scales with the number of results returned, with a minimum of 1
credit per call (an empty result set still bills the minimum).
### Responses:
**200**: Successful Response (Success Response)
Content-Type: application/json
**Example Response:**
```json
{
"success": true,
"meta": {
"requestId": "Requestid",
"timestamp": "Timestamp"
}
}
```
**Output Schema:**
```json
{
"properties": {
"success": {
"type": "boolean",
"title": "Success",
"description": "Whether the request was successful",
"default": true
},
"data": {
"description": "Response data payload"
},
"error": {
"description": "Error details if request failed"
},
"meta": {
"description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
"properties": {
"requestId": {
"type": "string",
"title": "Requestid",
"description": "Unique request identifier"
},
"timestamp": {
"type": "string",
"title": "Timestamp",
"description": "Response timestamp in ISO 8601 format"
},
"total": {
"title": "Total",
"description": "Total number of records"
},
"page": {
"title": "Page",
"description": "Current page number"
},
"pageSize": {
"title": "Pagesize",
"description": "Number of records per page"
},
"totalPages": {
"title": "Totalpages",
"description": "Total number of pages"
},
"creditsRemaining": {
"title": "Creditsremaining",
"description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
},
"creditsConsumed": {
"title": "Creditsconsumed",
"description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
},
"creditsRemainingExact": {
"title": "Creditsremainingexact",
"description": "Remaining API credits, precise to 1 decimal place"
},
"creditsConsumedExact": {
"title": "Creditsconsumedexact",
"description": "Credits consumed by this request, precise to 1 decimal place"
},
"tokensUsage": {
"description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
}
},
"type": "object",
"required": [
"requestId",
"timestamp"
],
"title": "ResponseMeta"
}
},
"type": "object",
"required": [
"meta"
],
"title": "OpenApiResponse[CrawlerSearch]",
"examples": []
}
```
**422**: Validation Error
Content-Type: application/json
**Example Response:**
```json
{
"detail": [
{
"loc": [],
"msg": "Message",
"type": "Error Type",
"ctx": {}
}
]
}
```
**Output Schema:**
```json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
```
