--- title: "Search the web" method: POST path: "/search" tags: ["Search"] --- # Search the web `POST /search` ## Request - Base URL: `https://api.onkernel.com` - URL: `https://api.onkernel.com/search` - Auth: HTTP bearer Returns ranked results from one serving provider. The default strategy selects a provider that supports the requested options. The fallback strategy tries providers in the supplied order. Results are not blended across providers. Portable filters may be approximated or omitted according to provider capabilities; warnings describe those outcomes unless strict_params is true. Native options apply only to their selected provider. ## Request body - SearchRequest - `content` union: Optional portable content retrieval. Pass true for defaults or an options object. Omission never starts Kernel browser work; provider-supplied content is still returned when available, including when requested through native options. Both inline and deferred retrieval use the same options schema. - true: Pass true to enable default portable content retrieval (auto source, markdown format, 10,000 char cap). - SearchContentOptions - `browser` SearchBrowserOptions - `browser_id` string: Existing browser session ID authorized for the caller and selected project. Reuses its cookies, proxy, and browser configuration; requests follow that browser's existing network access behavior, with no additional destination allowlist in this endpoint. Kernel does not delete a caller-supplied browser. Render mode uses a temporary tab; website activity may still change shared cookies and storage. When omitted and any result needs browser retrieval, Kernel creates one temporary browser for the request using the dashboard launch defaults (headful, stealth, default proxy), tags it with search_id, and deletes it when the request finishes. It is billed and counts toward browser concurrency like any other browser. A concurrency rejection returns 429 for source=browser; for source=auto, results with retained content are still returned and the rest report the rejection. - `mode` 'curl' | 'render': Curl uses the browser HTTP stack without navigation or JavaScript execution. Render navigates a temporary page and extracts from its DOM. The selected mode is used for the retrieval. - `format` 'markdown' | 'text' - `max_age_hours` integer: For source=auto, maximum acceptable age of retained provider content, measured from when the search received it from the provider. A value of 0 disables reuse of retained content, so every result is fetched through a browser. source=provider reuses retained provider content without freshness validation. source=browser always fetches through a browser and does not use this age limit. - `max_chars` integer: Per-result Unicode character limit after extraction. Retained provider content cannot exceed what was stored at search time; such results report truncated when the stored text was already truncated. - `source` 'auto' | 'provider' | 'browser': auto uses retained provider content within max_age_hours; for deferred retrieval it falls back to a Kernel browser (caller-supplied or temporary) for results without it. Inline retrieval never uses a browser. provider reuses retained provider content when available, without freshness validation, and never provisions a browser. browser fetches each URL through a Kernel browser, either caller-supplied or temporary. No option makes a new provider request. Defaults to auto for both inline and deferred retrieval. Missing documents produce per-result unavailable outcomes, not request failures. - `timeout_ms` integer: Per-result deadline including capacity acquisition, retrieval, and extraction. Also bounded by the overall request deadline. - `country` string: ISO 3166-1 alpha-2 search locale preference. - `end_date` string, date: Inclusive publication-date upper bound; must not precede start_date. If recency is also supplied, recency takes precedence with a warning. Unsupported or approximated filtering is reported, or rejected under strict_params. - `exclude_domains` string[]: Hostname exclusions, with the same best-effort/strict behavior as include_domains. Provider-specific combinations that cannot be represented are reported via warnings or rejected in strict mode. - `include_domains` string[]: Hostname inclusion preference, matching a hostname and its subdomains. Empty means unrestricted. Translated, emulated, or dropped with a warning according to provider capability unless strict_params is true. Native boost modes remain advisory and are identified in warnings. - `include_raw` boolean: Include untouched per-result payloads and the full serving-provider response in raw fields. Off by default; native top-level outputs such as answer remain available without it. - `language` string: BCP 47 search language preference. - `max_results` integer: Requested result count from 1 through 100. The effective count is clamped to the serving provider's cap with a warning. Effective native counts are the lower of this limit and supplied provider-native count aliases. Strict mode rejects unsupported counts. - `query` string, required: Primary search query. A provider-native multi-query option applies only to that provider; other providers in a fallback chain receive this query. - `recency` 'hour' | 'day' | 'week' | 'month' | 'year': Relative search window. Takes precedence over start_date/end_date with a warning if both are set. Provider-native recency behavior is retained, including documented hour-to-day widening. Unsupported filters are rejected only in strict mode. - `safe_search` 'off' | 'moderate' | 'strict': Optional safety preference. Omit to use provider defaults. Unsupported values are dropped with a warning unless strict_params is true. A search filter is not an authorization boundary. - `start_date` string, date: Inclusive publication-date lower bound. If recency is also supplied, recency takes precedence with a warning. Provider date semantics, precision, and unsupported filters are reported; unknown source dates are not fabricated or universally post-filtered. - `strategy` union: Typed provider selection and routing strategy. - SearchAutoStrategy - `fallback_on` SearchFallbackCondition[]: Conditions that advance to the next provider under auto routing or an explicit providers chain. Ignored when provider pins a single provider. error means a retryable provider failure, including rate limiting, not invalid caller input or caller quotas. empty means zero results after required filtering. An empty list disables fallback. If every attempt is empty or fails, the response is the first valid empty response with the full attempt trail, or a 502 if none succeeded. - `provider_options` SearchProviderTarget[]: Provider targets available to auto routing, each paired with typed native options. Provider names must be unique. - union: Provider name paired with its typed native options. - SearchBraveTarget - `options` SearchBraveOptions - … - `provider` 'brave', required - SearchExaTarget - `options` SearchExaOptions - … - `provider` 'exa', required - SearchPerplexityTarget - `options` SearchPerplexityOptions - … - `provider` 'perplexity', required - SearchContextTarget - `options` SearchContextOptions - … - `provider` 'context', required - SearchParallelTarget - `options` SearchParallelOptions - … - `provider` 'parallel', required - SearchValyuTarget - `options` SearchValyuOptions - … - `provider` 'valyu', required - SearchOctenTarget - `options` SearchOctenOptions - … - `provider` 'octen', required - SearchYouTarget - `options` SearchYouOptions - … - `provider` 'you', required - SearchTavilyTarget - `options` SearchTavilyOptions - … - `provider` 'tavily', required - SearchSerpApiTarget - `options` SearchSerpApiOptions - … - `provider` 'serpapi', required - `type` 'auto', required: Let Kernel choose an eligible provider by capability fit. - SearchPinnedStrategy - `provider` union, required: Provider name paired with its typed native options. - SearchBraveTarget - `options` SearchBraveOptions - `count` integer: Provider-native count. Lower-only alias for max_results; cannot raise the effective result cap. - `extra_snippets` boolean: Request additional snippets from Brave. - `goggles` string: Goggles re-ranking definition URL. - `goggles_id` string: Deprecated Brave Goggle identifier. Prefer goggles. - `include_fetch_metadata` boolean: Include Brave's fetch metadata. - `offset` integer: Page offset supported by Brave. - `operators` string: Brave search operators. - `result_filter` string: Comma-separated result types to include, e.g. "web,news". - `search_lang` string: Language of the search, e.g. "en". - `spellcheck` boolean: Apply Brave's query spellcheck. - `ui_lang` string: Language for UI strings in the response. - `units` 'metric' | 'imperial': Measurement units. - `provider` 'brave', required - SearchExaTarget - `options` SearchExaOptions - `category` string: Provider data-category hint. - `compliance` string: Provider-native compliance controls. Requires support and authorization on the provider account. - `contents` SearchExaOptionsContents: Provider-native content retrieval. Available without requesting Kernel browser retrieval; may incur provider retrieval charges. - … - `maxAgeHours` number: Provider-native cache-age control. Unlike content.max_age_hours, this retains Exa semantics, including any native sentinel values. It does not imply a cross-provider freshness guarantee. - `numResults` integer: Provider-native count. Lower-only alias for max_results. - `type` 'auto' | 'fast' | 'instant': Search mode supported by Exa. - `provider` 'exa', required - SearchPerplexityTarget - `options` SearchPerplexityOptions - `last_updated_after_filter` string: MM/DD/YYYY. Filters by last-updated date, not published date. - `last_updated_before_filter` string: MM/DD/YYYY upper bound on last-updated date. - `max_results` integer: Provider-native count. Lower-only alias for max_results. - `max_tokens` integer: Values outside the documented range are rejected. - `max_tokens_per_page` integer: Per-page token cap. - `query` string[]: Provider-native multi-query form, applied only to Perplexity. Other fallback providers receive the top-level query. Each query may incur a separate provider charge. - `search_context_size` 'low' | 'medium' | 'high': Amount of page content Perplexity extracts per result. Defaults to medium unless max_tokens or max_tokens_per_page is set. - `search_language_filter` string[]: ISO 639-1 language codes, max 20. - `provider` 'perplexity', required - SearchContextTarget - `options` SearchContextOptions - `country` string: ISO 3166-1 alpha-2 country code. - `excludeDomains` string[]: Blocklist of result domains. - `freshness` 'last_24_hours' | 'last_week' | 'last_month' | 'last_year': Restrict results to content published within this window. - `includeDomains` string[]: Allowlist of result domains. - `markdownOptions` SearchContextMarkdownOptions - … - `numResults` integer: Number of results to request from Context.dev. - `queryFanout` boolean: Expand the query into multiple parallel variants. - `tags` string[]: Usage tracking tags. - `timeoutMS` integer: Context.dev request timeout in milliseconds. - `provider` 'context', required - SearchParallelTarget - `options` SearchParallelOptions - `advanced_settings` SearchParallelOptionsAdvancedSettings: Explicit search settings. Unified search parameters are re-applied to overlapping settings; native result counts are lower-only. - … - `client_model` string: Client model hint. - `max_chars_total` integer: Cap total characters returned. - `mode` 'turbo' | 'fast' | 'basic' | 'advanced': Search mode. Basic is used when omitted; each mode can have different latency and charges. - `objective` string: The goal behind the search, stated separately from the query. - `search_queries` string[]: Provider-native multi-query search. Defaults to [query] for this provider. - `session_id` string: Group related searches. - `provider` 'parallel', required - SearchValyuTarget - `options` SearchValyuOptions - `fast_mode` boolean: Trade depth for latency. - `historical_cache` boolean: Allow historical cached results. - `include_abstracts` boolean: Include abstracts for academic sources. - `instructions` string: Natural-language retrieval guidance. - `is_tool_call` boolean: Mark the search as an agent tool call. - `max_num_results` integer: Provider-native count. Lower-only alias for max_results. - `max_price` number: Provider-native USD-per-thousand-results price ceiling. Forwarded to Valyu. - `relevance_threshold` number: Provider-native minimum relevance threshold. Not a normalized cross-provider score. - `response_length` 'short' | 'medium' | 'large' | 'max': Provider result-content length preset. - `search_type` string: Corpus selector, including all, web, proprietary, and news. Provider corpus choice may change billing; Kernel does not force web-only searches. - `source_biases` string[]: Bias retrieval toward these sources. - `url_only` boolean: Return URLs without content. - `provider` 'valyu', required - SearchOctenTarget - `options` SearchOctenOptions - `count` integer - `end_time` string, date-time - `exclude_domains` string[] - `exclude_text` string[] - `format` 'markdown' | 'text' - `full_content` object - … - `highlight` object - … - `include_domains` string[] - `include_images` boolean - `include_text` string[] - `language` string[] - `safesearch` 'off' | 'strict' - `start_time` string, date-time - `time_basis` 'auto' | 'published' | 'crawled' - `time_range` string - `topic` 'general' | 'news' - `provider` 'octen', required - SearchYouTarget - `options` SearchYouOptions - `boost_domains` string[]: Prefer these domains without excluding others. Cannot be combined with include_domains if the provider does not accept the combination. - `count` integer: Provider-native per-section count. Lower-only alias for max_results. Web and news sections may produce more rows than Kernel returns. - `crawl_timeout` integer: Native extraction timeout in seconds, bounded by the remaining Kernel request deadline. - `extraction` SearchYouOptionsExtraction: Provider-native page extraction. Both modes may incur per-row charges; full_page may retrieve web and news rows. - … - `knowledge` 'core': Request licensed-data output. URL-less knowledge entries are not converted into web results; include_raw exposes the full provider response separately. - `language` string: BCP 47 result language from You.com's 51-value enum, e.g. "EN", "JA". Default EN. - `offset` integer: Page offset supported by You.com. - `provider` 'you', required - SearchTavilyTarget - `options` SearchTavilyOptions - `auto_parameters` boolean: Allow the provider to choose search parameters. May select a different billing tier; explicit caller values retain provider-native precedence. - `chunks_per_source` integer: Provider excerpts per source, up to 500 characters each. - `exact_match` boolean: Require the quoted phrases in the query verbatim, bypassing semantic matches. - `filter_by_language` boolean: Strictly filter non-matching languages. Requires `language`. - `include_answer` union: Request the provider's generated answer. Returned as answer on the search response, independently of include_raw. - … - `include_domains_mode` 'filter' | 'boost': Native filter versus ranking boost semantics. Boost influences ranking rather than restricting results to the listed domains. Requires include_domains. - `include_favicon` boolean: Favicon URL per result. - `include_image_descriptions` boolean: Describe each image. Needs include_images. - `include_images` boolean: Query-related images plus per-result images. - `include_raw_content` union: Request native full-page content. Defaults to markdown when omitted for this provider, False disables that native retrieval; it does not disable explicitly requested Kernel browser retrieval. - … - `language` string: ISO 639-1 code or English language name. Ranking boost unless filter_by_language. - `max_results` integer: Provider-native count. Lower-only alias for max_results. - `search_depth` 'advanced' | 'basic' | 'fast' | 'ultra-fast': Provider relevance and latency tier. Some tiers cannot be combined with native safe search; conflicts are described in warnings. - `topic` 'general' | 'news' | 'finance': Provider corpus selector. Publication metadata depends on the selected topic. - `provider` 'tavily', required - SearchSerpApiTarget - `options` SearchSerpApiOptions - `device` 'desktop' | 'mobile' | 'tablet': Device profile used for the search. - `engine` string, required: SerpApi engine identifier. The Kernel integration currently supports google only. - `filter` 0 | 1: Google duplicate-content filter. - `gl` string: Two-letter Google country code. - `google_domain` string: Google domain to search when using the google engine. - `hl` string: Interface language code. - `location` string: Free-form geographic location used for localized results. - `nfpr` 0 | 1: Google auto-correction filter. - `no_cache` boolean: When true, bypass SerpApi cached results when supported. - `num` integer: Number of results requested from the search engine. - `safe` 'active' | 'off': Safe-search setting for engines that support it. - `start` integer: Zero-based result offset for pagination. - `tbm` string: Google vertical search selector, such as images, video, news, or shopping. - `tbs` string: Google time and search modifiers, including freshness filters. - `provider` 'serpapi', required - `type` 'pinned', required: Use exactly the selected provider with no cross-provider fallback. - SearchFallbackStrategy - `fallback_on` SearchFallbackCondition[]: Conditions that advance to the next provider under auto routing or an explicit providers chain. Ignored when provider pins a single provider. error means a retryable provider failure, including rate limiting, not invalid caller input or caller quotas. empty means zero results after required filtering. An empty list disables fallback. If every attempt is empty or fails, the response is the first valid empty response with the full attempt trail, or a 502 if none succeeded. - `providers` SearchProviderTarget[], required: Ordered provider targets. Provider names must be unique. - union: Provider name paired with its typed native options. - SearchBraveTarget - `options` SearchBraveOptions - … - `provider` 'brave', required - SearchExaTarget - `options` SearchExaOptions - … - `provider` 'exa', required - SearchPerplexityTarget - `options` SearchPerplexityOptions - … - `provider` 'perplexity', required - SearchContextTarget - `options` SearchContextOptions - … - `provider` 'context', required - SearchParallelTarget - `options` SearchParallelOptions - … - `provider` 'parallel', required - SearchValyuTarget - `options` SearchValyuOptions - … - `provider` 'valyu', required - SearchOctenTarget - `options` SearchOctenOptions - … - `provider` 'octen', required - SearchYouTarget - `options` SearchYouOptions - … - `provider` 'you', required - SearchTavilyTarget - `options` SearchTavilyOptions - … - `provider` 'tavily', required - SearchSerpApiTarget - `options` SearchSerpApiOptions - … - `provider` 'serpapi', required - `type` 'fallback', required: Try providers in order and advance when fallback_on matches the outcome. - `strict_params` boolean: When false, unsupported portable parameters are omitted and approximations are described in warnings. When true, every supplied portable parameter must be honored exactly. Requests that cannot be served with those parameters are rejected. This does not guarantee identical rankings or document timestamps across indexes. Authentication and project isolation are always enforced. - `timeout_ms` integer: Overall deadline across search attempts and inline retrieval. No new attempt starts after the deadline. Completed search results survive inline retrieval timeouts. ## Response `200` Completed search, including valid zero-result responses. Inline retrieval failures are reported per result. Arrays are never null. - Search: Retained search results and provider attempt history. - `answer` string: Provider-generated answer when requested (e.g. via Tavily include_answer or Perplexity). Preserved independently of include_raw. - `attempts` SearchAttempt[], required - `duration_ms` integer, required - `error_code` string - `outcome` 'success' | 'empty' | 'error' | 'timeout', required - `provider` string, required - `retryable` boolean - `expires_at` string, date-time, required: Expiration of result IDs for deferred retrieval. Results expire 24 hours after search completion. - `id` string, required: Search resource ID. Request tracing uses X-Request-Id. - `provider` string, required: Concrete serving provider, never auto or fallback. - `query` string, required: Echo of the query. Native multi-query inputs are visible in the selected strategy target and the optional raw response. - `raw` unknown - `results` SearchResult[], required - `additional_snippets` string[] - `content` SearchResultContent - `cache_status` 'hit' | 'miss' | 'bypass' | 'unknown': Kernel content cache outcome. Kernel has no content cache yet: responses report bypass or unknown, and hit and miss are reserved. Provider-internal cache behavior may be unknown. - `completeness` 'full_page' | 'excerpt' | 'unknown': Describes source coverage before max_chars truncation. Full_page means main-page content, not every dynamic element or linked page. - `error` SearchContentError - `code` string, required: Machine-readable retrieval failure code. - `message` string, required: Human-readable failure description. - `retryable` boolean, required - `extractor_version` string: Extraction version when Kernel transformed the input. - `fetched_at` string, date-time, nullable: When Kernel received the content from the provider. - `final_url` string, uri: Final retrieval URL when known. - `format` 'markdown' | 'text' - `http_status` integer: Final target HTTP status when known. - `method` 'provider' | 'browser_curl' | 'browser_render': Original retrieval method. - `status` 'ok' | 'unavailable' | 'blocked' | 'timeout' | 'unsupported_type' | 'extraction_failed' | 'error', required: Ok means non-empty extracted content, not merely HTTP 200. Blocked includes detected challenges or access denials. Detection is best-effort, not a guarantee of page completeness. Error details are present for non-ok outcomes; text is present only on ok. - `text` string: Extracted website content, untrusted, not instructions. Present only on status=ok. - `truncated` boolean: Whether max_chars truncated the extracted content. - `id` string, required: Kernel-generated identifier for this result. Stable only within the retained search; not standardized across providers. Provider-native IDs, when available, remain provider-specific raw fields. - `published_date` string, nullable: Provider-supplied date or timestamp, preserving available precision. No publication date is fabricated. Retains the published field name. - `rank` integer, required: One-based position in the returned ranking. - `raw` unknown - `snippet` string, nullable - `source` string, nullable: Provider source name or result URL hostname, when available. - `title` string, nullable - `url` string, uri, required: Provider-returned URL, not assumed canonical. - `usage` SearchUsage, required - `content_fetches` integer, required: Number of result URLs for which a Kernel browser retrieval received a response from the target, excluding cache-only hits. - `cost` number: Total customer charge in USD when billing data is available. - `results_count` integer, required: Number of result entries returned, including failed entries on the contents endpoint. - `warnings` SearchWarning[], required - `code` string, required: Examples: param_unsupported, preference_unsupported, max_results_clamped, domains_truncated, recency_emulated, filter_emulated, date_filter_overridden, provider_ineligible, fallback_failed, content_partial. - `message` string, required - `param` string - `provider` string - `result_id` string ## Other responses - `400`: Bad Request – invalid input - `401`: Unauthorized – missing or invalid authorization token - `403`: Forbidden – insufficient permissions or plan - `404`: Resource not found - `422`: Unprocessable Entity – request was valid but the operation failed - `429`: Too Many Requests – rate limit exceeded - `500`: Internal Server Error - `502`: Search providers could not complete the request. Details contain per-attempt failure codes and provider names. - `503`: No provider is currently available for the request. - `504`: Overall deadline exceeded before a search response was available. ## Changes - **2026-10-23** `1108efa87717`: 2 info - the `fallback_on` request property default value changed from `error, timeout` to `error, timeout, empty` - the `fallback_on` request property default value changed from `error, timeout` to `error, timeout, empty` - **2026-10-05** `de9be1ff2519`: 6 info - the `highlights` request property default value `true` was added - the `highlights` request property default value `true` was added - the `highlights` request property default value `true` was added - the `search_context_size` request property default value `medium` was added - …2 more - **2026-09-30** `1c1d8e9f2c9d`: 1 info - added the non-success response with the status `422` - **2026-09-22** `c5f760559289`: 1 info - endpoint added [Operation history](https://skmtc.dev/onkernel/apis/kernel-api/changes/search/post.md) --- [API](https://skmtc.dev/onkernel/apis/kernel-api.md) - [All operations](https://skmtc.dev/onkernel/apis/kernel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/onkernel/apis/kernel-api/revisions/0f6cf4f58fe6?raw)