Skip to main content
Reference material for Web Search: request parameters, response body, error handling, common gotchas, and the API summary. For walk-through examples, see Web Search and Recipes. For result shapes and field presence by source, see Source types.

​
Request parameter reference

ParameterTypeRequiredDefaultDescription
querystringYes—Search query text. Max 5,000 characters. Supports search operators like site: and filetype:.
locationstringNo—ISO 3166-1 alpha-2 country code for region-specific results (e.g., "US", "GB", "JP").
sourcesstring[]No—Sources to query: web, news, scholar-articles, scholar-articles-enriched, scholar-author, ai, social. Current platform behavior: omitting this field searches all sources.
sitestringNo—Restrict results to a domain (e.g., "linkedin.com/company", "github.com"). Max 500 characters.
start_dateintegerNo—Unix timestamp (seconds). Only results after this date.
end_dateintegerNo—Unix timestamp (seconds). Only results before this date. Must be > start_date.
human_modebooleanNofalseAttempt a browser-like retrieval path when standard search access is blocked by bot protection.
pageintegerNo1Number of result pages to aggregate into the response. Minimum: 1.

​
Response fields reference

FieldTypeDescription
successbooleanWhether the search executed successfully.
querystringThe query as interpreted by the API (includes site: prefix if site was set).
timestampintegerUnix timestamp in milliseconds when the search was performed.
resultsarraySearch results. Shape varies by source — see Source types.
metadata.totalResultsintegerTotal number of results available across all pages (may exceed the number in the results array if you requested fewer pages).
metadata.failedPagesarrayPage numbers that failed to return results.
metadata.emptyPagesarrayPage numbers that returned no results.
Timestamps: Search timestamp is in milliseconds. Fetch timestamp is in seconds. Divide Search timestamps by 1000 when comparing across endpoints.

​
Error handling

Search returns 400 for invalid requests and 401 for auth failures. 
{
    "error": {
        "type": "invalid_request",
        "message": "query: This field is required.",
        "metadata": []
    }
}

​
Common gotchas

MistakeFix
Omitting sources and expecting uniform resultsDifferent sources return different fields. Specify sources explicitly for predictable parsing.
Using site with scholar-author or ai sourcessite only applies to web and news sources. It has no effect on academic or deep research searches.
Expecting snippet in deep research mode resultsDeep research mode returns content and references instead of snippet and position.
Expecting position in scholar-author resultsAcademic author results don’t have position — they have name, affiliation, citations, etc.
Using start_date >= end_datestart_date must be strictly less than end_date.

​
API reference summary

DetailValue
EndpointPOST /web/search/live
AuthBearer token + x-api-version: 2025-11-01
Pricing1 credit per query
Requestquery (required). Optional: location, sources, site, start_date, end_date, human_mode, page.
ResponseObject: { success, query, timestamp, results[], metadata }
Errors400 (bad request), 401 (bad auth)
See the full API reference for the complete OpenAPI schema.