---
title: "Search the web"
method: GET
path: "/search"
tags: ["Search"]
---

# Search the web

`GET /search`

## Request

- Base URL: `https://api.search.tinyfish.ai`
- URL: `https://api.search.tinyfish.ai/search`
- Auth: API key in header `X-API-Key`

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

**Location and language resolution:**
- If `location` is set but `language` is not, the language auto-resolves to the most predominantly used language in that country.
- If `language` is set but `location` is not, the location auto-resolves to the country where that language is most predominantly used.
- If neither `location` nor `language` is set, defaults to `US` and `en`.

## Query parameters

- `query` string, required: Search query
- `purpose` string: Why this search is being run — the underlying goal or task the results will be used for. Used to better rank results against your intent.
- `location` string: Country code for geo-targeted results
- `language` string: Language code for result language
- `include_domains` string: Comma-separated list of domains to restrict results to
- `exclude_domains` string: Comma-separated list of domains to exclude from results
- `domain_type` 'web' | 'news' | 'research_paper': Type of search to perform: "web" for standard results, "news" for news articles, "research_paper" for academic papers. Defaults to "web".
- `after_date` string: Return results after this date (YYYY-MM-DD)
- `before_date` string: Return results before this date (YYYY-MM-DD)
- `recency_minutes` integer: Return results from the past N minutes (1 to 5,256,000).
- `pub_year_min` integer: Return research papers published on or after this year (0-9999, inclusive). Only supported for domain_type=research_paper.
- `pub_year_max` integer: Return research papers published on or before this year (0-9999, inclusive). Only supported for domain_type=research_paper.
- `page` integer, nullable: Page number for pagination, starting from 0 (max 10)
- `include_thumbnail` 'true' | 'false': When "true", each result includes a thumbnail_url when available. Defaults to false.
- `fetch` string: JSON-encoded fetch configuration object.

## Response `200`

Search completed successfully.

- object: Search response with results
  - `query` string, required: The search query that was executed
  - `results` object[], required: Array of search results
    - `position` integer, required: Position in search results
    - `site_name` string, required: Site name
    - `snippet` string, required: Text snippet from the result
    - `title` string, required: Page title
    - `url` string, uri, required: Result URL
    - `thumbnail_url` string, uri: Thumbnail image URL, present only when include_thumbnail=true and a thumbnail is available
    - `fetch` unknown
    - `fetch_error` unknown
    - `date` string: Publication date, present for news and some web results
    - `publisher` string: Publisher name, present for news results when domain_type=news
    - `authors` string[]: Author list, present for academic results when domain_type=research_paper
    - `venue` string: Journal or conference name, present when domain_type=research_paper
    - `year` integer: Publication year, present when domain_type=research_paper
    - `cited_by_count` integer: Citation count, present when domain_type=research_paper
    - `pdf_url` string: PDF URL, present when domain_type=research_paper and a PDF is available
  - `total_results` integer, required: Total number of results
  - `page` integer, required: The current page number, starting from 0
  - `request_id` string: Request correlation ID, also returned as the X-Request-ID response header. Present only when any result carries a fetch_error; include it when reporting failed fetches.

## Other responses

- `400`: Invalid request - missing or invalid query parameters
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment required - daily free Search allowance used and the wallet balance is zero or below (`INSUFFICIENT_CREDITS`), or used on a product that does not charge the wallet (`FREE_ALLOWANCE_EXHAUSTED`)
- `403`: Forbidden - Search request forbidden by the upstream service
- `404`: Search API is not available
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: Search service unavailable

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/6c73a54df35c?raw)