---
title: "Web Search"
method: POST
path: "/v1/search"
tags: ["Search"]
---

# Web Search

`POST /v1/search`

## Request

- Base URL: `https://apipie.ai`
- URL: `https://apipie.ai/v1/search`
- Auth: API key in header `Authorization`

Perform a web search and return results

## Request body

- SearchRequest
  - `query` string, required: Search query string
  - `search_provider` 'google' | 'valyu': Search provider (google, or valyu (Valyu includes search & scrape in one, with similarity selection))
  - `geo` string: Country code for localized results
  - `lang` string: Language code for search/results
  - `results` integer: Number of results to return per search (1-100 for google/brightdata, 1-20 for valyu)
  - `safeSearch` 1 | -1 | -2: Safe search filtering level (1=on, -1=moderate, -2=off) - not supported by valyu
  - `user` string: User identifier for billing observability purposes
  - `whitelist` string[]: Array of sources to include in search results (domains, URLs, or dataset names) - only supported by valyu provider
  - `blacklist` string[]: Array of sources to exclude from search results (domains, URLs, or dataset names) - only supported by valyu provider
  - `max_price` number, float: Valyu | Maximum price in dollars for a thousand retrievals (CPM). Only applies when provided. If not provided, adjusts automatically based on search type and max number of results.
  - `start_date` string, date: Valyu | Start date for time-filtered searches (YYYY-MM-DD)
  - `end_date` string, date: Valyu | End date for time-filtered searches (YYYY-MM-DD)
  - `instructions` string: Custom instructions for query rewriting and result reranking. Max 500 characters. (Preferred over category)
  - `relevance_threshold` number, float: Minimum relevance score (0.0-1.0) for results after reranking. Results below this threshold are filtered out.
  - `fast_mode` boolean: Valyu | Enable fast mode for reduced latency but shorter results. Best for general purpose queries. Cannot be used with search_type "proprietary".
  - `url_only` boolean: Return only URLs without full content extraction. Only available when search_type is "web" or "news". Skips reranking.
  - `source_biases` object: Bias values for specific sources to influence ranking without hard filtering. Keys are domains (e.g., "nasa.gov") or URL paths. Values are integers from -5 (strong demotion) to +5 (strong boost).
  - `response_length` string: valyu | Controls the length of content returned per result. Can be an integer for character count or predefined values: short (25k), medium (50k), large (100k), max (full)
  - `is_tool_call` boolean: Valyu | Tunes retrieval process based on whether the API is being called by an AI agent as a tool call, or a user query.

## Response `200`

Successful search with results

- SearchResponse
  - `results` object
  - `usage` SearchUsage
    - `search_id` string
    - `timestamp` integer
    - `search_provider` string
    - `keywords` string
    - `total_records` integer
    - `requested_records` integer
    - `returned_records` integer
    - `cost` number, float
    - `latencyMs` integer

## Other responses

- `400`: Bad request or search failed

---

[API](https://skmtc.dev/apipie/apis/introduction.md) · [All operations](https://skmtc.dev/apipie/apis/introduction/llms.txt) · [OpenAPI document](https://skmtc.dev/apipie/apis/introduction/revisions/f8386be4eb3f?raw)