Skip to main content

Search

POST 

/v1/tools/search

Search the web for a query and return a ranked list of structured results. See the Search & Fetch guide for supported query operators, error handling, and billing.

Request​

Body

required

    query stringrequired

    Minimum characters: 1

    Maximum characters: 128

    The search query. Supports operators such as site:, -site:, and quoted phrases. Must contain 1 to 128 Unicode characters and cannot be all whitespace.

    count integer

    Possible values: >= 1 and <= 50

    Default value: 10

    The number of results to return, between 1 and 50. Defaults to 10.

    ori_question stringnullable

    Minimum characters: 1

    Maximum characters: 128

    The user's original question that triggered the search, between 1 and 128 characters. Providing it can improve query understanding. null is treated as not provided.

    localization string

    Default value: ""

    An optional IP address used to localize search results. Defaults to an empty string.

    need_content boolean

    Default value: false

    Whether to return page content in content. Defaults to false; when false, content is always an empty string.

Responses​

OK, returns the search results.

Schema

    results

    object[]

    required

    The search results. Empty when the query matches no results.

  • Array [

  • rerank_score floatrequired

    Possible values: >= 0 and <= 3

    A relevance score from 0 to 3 that combines signals such as relevance, authority, and freshness. Scores of 1.5 or above are considered high-quality results.

    title stringrequired

    The title of the search result.

    url stringrequired

    The URL of the search result.

    snippet stringrequired

    A short summary related to the query, typically 100 to 200 characters, intended for display in a UI.

    summary stringrequired

    A long summary related to the query, typically 600 to 800 characters, intended to be read by a model.

    content stringrequired

    The page content. Empty when need_content is false or when the content is unavailable.

    site_name stringnullablerequired

    The name of the site, or null when unavailable.

    site_icon stringnullablerequired

    The URL of the site icon, or null when unavailable.

    date date-timenullablerequired

    The publication time in UTC, formatted as RFC 3339, or null when unknown.

    authority integerrequired

    Possible values: >= -1 and <= 4

    The authority tier of the page, 0 to 4 (-1 means unknown). Values of 3 or above indicate highly authoritative sources.

  • ]

Loading...