Search

Web Search

Perform a web search and return results

post/v1/search

Request

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

Request body

querystring required

Search query string

search_provider'google' | 'valyu'

Search provider (google, or valyu (Valyu includes search & scrape in one, with similarity selection))

geostring

Country code for localized results

langstring

Language code for search/results

resultsinteger

Number of results to return per search (1-100 for google/brightdata, 1-20 for valyu)

safeSearch1 | -1 | -2

Safe search filtering level (1=on, -1=moderate, -2=off) - not supported by valyu

userstring

User identifier for billing observability purposes

whiteliststring[]

Array of sources to include in search results (domains, URLs, or dataset names) - only supported by valyu provider

blackliststring[]

Array of sources to exclude from search results (domains, URLs, or dataset names) - only supported by valyu provider

max_pricenumber 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_datestring date

Valyu | Start date for time-filtered searches (YYYY-MM-DD)

end_datestring date

Valyu | End date for time-filtered searches (YYYY-MM-DD)

instructionsstring

Custom instructions for query rewriting and result reranking. Max 500 characters. (Preferred over category)

relevance_thresholdnumber float

Minimum relevance score (0.0-1.0) for results after reranking. Results below this threshold are filtered out.

fast_modeboolean

Valyu | Enable fast mode for reduced latency but shorter results. Best for general purpose queries. Cannot be used with search_type "proprietary".

url_onlyboolean

Return only URLs without full content extraction. Only available when search_type is "web" or "news". Skips reranking.

source_biasesobject

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_lengthstring

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_callboolean

Valyu | Tunes retrieval process based on whether the API is being called by an AI agent as a tool call, or a user query.

Example request

{
  "query": "latest AI developments",
  "search_provider": "google",
  "geo": "us",
  "lang": "en",
  "results": 20,
  "user": "user123",
  "whitelist": [
    "arxiv.org",
    "reuters.com",
    "valyu/valyu-arxiv"
  ],
  "blacklist": [
    "reddit.com",
    "twitter.com",
    "news.ycombinator.com"
  ],
  "max_price": 30,
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "instructions": "Focus on peer-reviewed research from the last 2 years",
  "relevance_threshold": 0.5,
  "fast_mode": true,
  "source_biases": {
    "nasa.gov": 5,
    "noaa.gov": 3,
    "nih.gov": 1,
    "example.com": -4
  },
  "response_length": "medium"
}

Response

Successful search with results

resultsobject

Example response

{
  "results": {
    "result1": {
      "url": "https://example.com/page1",
      "title": "Example Page 1",
      "description": "Description of page 1"
    },
    "result2": {
      "url": "https://example.com/page2",
      "title": "Example Page 2",
      "description": "Description of page 2"
    }
  },
  "usage": {
    "search_id": "nai-123e4567-e89b-12d3-a456-426614174000",
    "timestamp": 1711729795000,
    "search_provider": "google",
    "keywords": "latest AI developments",
    "total_records": 1000000,
    "requested_records": 20,
    "returned_records": 20,
    "cost": 0.03,
    "latencyMs": 1200
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.