---
title: "Search the public web"
method: POST
path: "/web/search"
tags: ["Retrieval"]
---

# Search the public web

`POST /web/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/web/search`
- Auth: API key in header `x-api-key`

Search Brave's public web results. limit (1-50, default 10) is honoured by reading up to 3 result pages; each successful result page read costs 3 credits, and optional page reads (5 credits each) remain scoped to each result host. country and language select the result locale (defaults us and en-us).

## Request body

- RetrievalplatformWebSearchRequest
  - `country` 'all' | 'ar' | 'at' | 'au' | 'be' | 'br' | 'ca' | 'ch' | 'cl' | 'cn' | 'de' | 'dk' | 'es' | 'fi' | 'fr' | 'gb' | 'gr' | 'hk' | 'id' | 'in' | 'it' | 'jp' | 'kr' | 'mx' | 'my' | 'nl' | 'no' | 'nz' | 'ph' | 'pl' | 'pt' | 'ru' | 'sa' | 'se' | 'sg' | 'tr' | 'tw' | 'us' | 'za': Country is the result country; defaults to us.
  - `exclude_domains` string[]
  - `include_domains` string[]
  - `language` 'de-de' | 'en-ca' | 'en-gb' | 'en-in' | 'en-us' | 'fi-fi' | 'fr-ca' | 'fr-fr' | 'ja-jp' | 'pt-br' | 'sq-al' | 'sw-ke' | 'zh-tw': Language is the result language; defaults to en-us.
  - `limit` integer: Limit is the number of results to return, 1 to 50 (default 10). Up to 3 result pages are read to reach it, at 3 credits per page read.
  - `max_credits` integer
  - `q` string, required
  - `scrape` RetrievaltypesFetchOptions
    - `max_age` integer
    - `only_main_content` boolean
    - `render` 'auto' | 'http' | 'browser'
    - `wait_for` integer
  - `scrape_limit` integer

## Response `200`

OK

- object: The Response struct is used for wrapping the API response with a code, message, and data.
  - `code` integer: Code is the HTTP status code or a custom code used to indicate the result of the request @example 200
  - `data` object: Data is the response data (can be any object or null) @example {"id": 1, "name": "John Doe"}
    - `coverage` RetrievaltypesSourceCoverage[]
      - `corpus_revision` string
      - `failure` RetrievaltypesFailure
        - `message` string
        - `reason` 'invalid_url' | 'unsupported_content_type' | 'blocked' | 'not_found' | 'rate_limited' | 'timeout' | 'upstream_error' | 'internal_error' | 'out_of_scope' | 'robots_disallowed' | 'duplicate' | 'limit_reached' | 'unsupported_filter' | 'unknown_source' | 'idempotency_conflict' | 'invalid_cursor' | 'result_expired' | 'full_text_unavailable' | 'budget_exhausted'
        - `retry_after_seconds` integer
        - `retryable` boolean
      - `indexed_at` string
      - `retrieved_at` string
      - `source_id` string
      - `status` 'ok' | 'failed' | 'not_indexed' | 'unsupported'
    - `items` WebretrievalWebSearchHit[]
      - `document` RetrievaltypesDocument
        - `content_sha256` string
        - `content_type` string
        - `document_id` string
        - `fetched_at` string
        - `final_url` string
        - `links` string[]
        - `markdown` string
        - `metadata` RetrievaltypesDocumentMetadata
          - `author` string
          - `description` string
          - `language` string
          - `modified_at` string
          - `published_at` string
          - `title` string
        - `passages` RetrievaltypesPassage[]
          - `locator` RetrievaltypesPassageLocator
            - `anchor` string
            - `end_byte` integer
            - `end_line` integer
            - `heading` string
            - `page` integer
            - `start_byte` integer
            - `start_line` integer
          - `passage_id` string
          - `score` number
          - `text` string
        - `revision` string
        - `source_url` string
        - `truncated` boolean
      - `fetch_failure` RetrievaltypesFailure
        - `message` string
        - `reason` 'invalid_url' | 'unsupported_content_type' | 'blocked' | 'not_found' | 'rate_limited' | 'timeout' | 'upstream_error' | 'internal_error' | 'out_of_scope' | 'robots_disallowed' | 'duplicate' | 'limit_reached' | 'unsupported_filter' | 'unknown_source' | 'idempotency_conflict' | 'invalid_cursor' | 'result_expired' | 'full_text_unavailable' | 'budget_exhausted'
        - `retry_after_seconds` integer
        - `retryable` boolean
      - `provider` string
      - `rank` integer
      - `retrieved_at` string
      - `snippet` string
      - `title` string
      - `url` string
    - `partial` boolean
    - `usage` RetrievaltypesUsage
      - `browser_renders` integer
      - `credits_charged` integer
      - `credits_released` integer
      - `credits_reserved` integer
      - `fetch_attempts` integer
      - `fetched_urls` integer
      - `input_tokens` integer
      - `output_tokens` integer
      - `search_requests` integer
      - `settlement_pending` boolean
    - `warnings` RetrievaltypesWarning[]
      - `code` 'source_failed' | 'source_not_indexed' | 'discovery_truncated' | 'ranking_window_limit' | 'imprecise_date_excluded' | 'content_unavailable' | 'cached_source_stale'
      - `message` string
      - `source_id` string
  - `msg` unknown

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/0497899e2016?raw)