---
title: "POST /v1/data/web/search"
method: POST
path: "/v1/data/web/search"
---

# POST /v1/data/web/search

`POST /v1/data/web/search`

## Request

- Base URL: `https://api.nano-gpt.com/api`
- URL: `https://api.nano-gpt.com/api/v1/data/web/search`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
  - none

Public Data API facade for web search. Supports normal API-key billing and accountless x402 quotes when called without Authorization or x-api-key and with x-x402: true.

## Headers

- `x-x402` 'true'

## Request body

- WebSearchRequest
  - `query` string: The query to execute. Required for search and Sofya research; omitted for Sofya fetch and extract.
  - `provider` 'linkup' | 'tavily' | 'exa' | 'kagi' | 'perplexity' | 'valyu' | 'brave' | 'sofya' | 'firecrawl': Search provider. Defaults to 'linkup'. 'openai-native' is not supported on /api/web.
  - `operation` 'search' | 'fetch' | 'extract' | 'research': Operation to run. Fetch, extract, and research are supported only when provider is sofya.
  - `depth` 'standard' | 'deep': Search depth. For Linkup: standard ($0.006) or deep ($0.06). Linkup standard is executed as fast under the hood.
  - `outputType` 'searchResults' | 'sourcedAnswer' | 'structured': Output format. Linkup supports searchResults, sourcedAnswer, and structured. Non-Linkup providers currently support searchResults only.
  - `structuredOutputSchema` string: JSON schema string defining the desired response format. Required when outputType is 'structured'
  - `includeImages` boolean: Whether to include image results in the search
  - `fromDate` string: Filter results from this date (YYYY-MM-DD format)
  - `toDate` string: Filter results until this date (YYYY-MM-DD format)
  - `excludeDomains` string[]: Array of domains to exclude from search results
  - `includeDomains` string[]: Array of domains to search exclusively
  - `maxResults` integer: Maximum results. Sofya search accepts 1-20.
  - `topic` 'general' | 'news': Sofya search or research topic.
  - `freshness` string: Sofya freshness window: day, week, month, year, or YYYY-MM-DD:YYYY-MM-DD.
  - `urls` string[]: One to ten URLs for Sofya fetch.
  - `includeRawHtml` boolean: Whether Sofya fetch should include raw HTML.
  - `url` string: URL for Sofya extract.
  - `prompt` string: Instructions describing what Sofya should extract from the URL.
  - `maxSources` integer: Maximum sources for Sofya research.

## Response `200`

Web search response with results based on output type

- WebSearchResponse
  - `data` union, required
    - object[]: Array of search results when outputType is 'searchResults'
      - `type` 'text' | 'image': Type of search result
      - `title` string: Title of the result
      - `url` string: URL of the result
      - `content` string: Content snippet (for text results)
      - `imageUrl` string: Image URL (for image results)
    - object: Provider-formatted object for sourcedAnswer, structured output, or Sofya extract/research
      - `answer` string: The comprehensive answer to the query
      - `sources` object[]
        - `name` string: Source name
        - `url` string: Source URL
        - `snippet` string: Relevant snippet from the source
    - object: Structured data matching the provided schema
  - `metadata` object, required
    - `query` string, required: The search query that was executed
    - `provider` string, required: The provider that executed the search
    - `operation` 'search' | 'fetch' | 'extract' | 'research', required: The resolved operation. This is search except for Sofya fetch, extract, and research requests.
    - `depth` 'standard' | 'deep', required: The search depth used
    - `outputType` 'searchResults' | 'sourcedAnswer' | 'structured', required: The output format used
    - `timestamp` string, required: ISO 8601 timestamp of when the search was performed
    - `cost` number, required: The cost of the search in USD

## Other responses

- `400`: Bad Request - Query parameter is required and must be a string
- `401`: Unauthorized - Invalid session or API key
- `402`: Payment Required - authenticated insufficient balance or opted-in accountless x402 quote
- `429`: Too Many Requests - Rate limit exceeded
- `503`: Service Unavailable - Provider key missing
- `504`: Gateway Timeout - Search failed or timed out

## Changes

- **2026-11-03** `cc8b07d75689`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nano-gpt/apis/nanogpt-api/changes/v1/data/web/search/post.md)

---

[API](https://skmtc.dev/nano-gpt/apis/nanogpt-api.md) - [All operations](https://skmtc.dev/nano-gpt/apis/nanogpt-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nano-gpt/apis/nanogpt-api/revisions/cc8b07d75689?raw)