--- title: "Search the web" method: POST path: "/web/search" tags: ["Web Scraping"] --- # Search the web `POST /web/search` ## Request - Base URL: `https://api.context.dev/v1` - URL: `https://api.context.dev/v1/web/search` - Auth: HTTP bearer Search the web and optionally return page content or relevant passages with each result. ## Request body - object - `query` string, required: Search query. Accepts natural language as well as Google-style search operators such as `site:`, `-site:`, `inurl:`, `intitle:`, quoted phrases, and `OR`. - `numResults` integer: Number of results to request and return (1–100). Defaults to 10. - `includeDomains` string[]: Allowlist — only return results from these domains. Up to 100 domains. Example: ["arxiv.org", "github.com"]. - `excludeDomains` string[]: Blocklist — drop results from these domains. Up to 100 domains. Example: ["pinterest.com", "reddit.com"]. - `freshness` 'last_24_hours' | 'last_week' | 'last_month' | 'last_year': Restrict results to content published within this window. - `country` 'af' | 'al' | 'dz' | 'as' | 'ad' | 'ao' | 'ai' | 'aq' | 'ag' | 'ar' | 'am' | 'aw' | 'au' | 'at' | 'az' | 'bs' | 'bh' | 'bd' | 'bb' | 'by' | 'be' | 'bz' | 'bj' | 'bm' | 'bt' | 'bo' | 'ba' | 'bw' | 'bv' | 'br' | 'io' | 'bn' | 'bg' | 'bf' | 'bi' | 'kh' | 'cm' | 'ca' | 'cv' | 'ky' | 'cf' | 'td' | 'cl' | 'cn' | 'cx' | 'cc' | 'co' | 'km' | 'cg' | 'cd' | 'ck' | 'cr' | 'ci' | 'hr' | 'cu' | 'cy' | 'cz' | 'dk' | 'dj' | 'dm' | 'do' | 'ec' | 'eg' | 'sv' | 'gq' | 'er' | 'ee' | 'et' | 'fk' | 'fo' | 'fj' | 'fi' | 'fr' | 'gf' | 'pf' | 'tf' | 'ga' | 'gm' | 'ge' | 'de' | 'gh' | 'gi' | 'gr' | 'gl' | 'gd' | 'gp' | 'gu' | 'gt' | 'gn' | 'gw' | 'gy' | 'ht' | 'hm' | 'va' | 'hn' | 'hk' | 'hu' | 'is' | 'in' | 'id' | 'ir' | 'iq' | 'ie' | 'il' | 'it' | 'jm' | 'jp' | 'jo' | 'kz' | 'ke' | 'ki' | 'kp' | 'kr' | 'kw' | 'kg' | 'la' | 'lv' | 'lb' | 'ls' | 'lr' | 'ly' | 'li' | 'lt' | 'lu' | 'mo' | 'mk' | 'mg' | 'mw' | 'my' | 'mv' | 'ml' | 'mt' | 'mh' | 'mq' | 'mr' | 'mu' | 'yt' | 'mx' | 'fm' | 'md' | 'mc' | 'mn' | 'ms' | 'ma' | 'mz' | 'mm' | 'na' | 'nr' | 'np' | 'nl' | 'an' | 'nc' | 'nz' | 'ni' | 'ne' | 'ng' | 'nu' | 'nf' | 'mp' | 'no' | 'om' | 'pk' | 'pw' | 'ps' | 'pa' | 'pg' | 'py' | 'pe' | 'ph' | 'pn' | 'pl' | 'pt' | 'pr' | 'qa' | 're' | 'ro' | 'ru' | 'rw' | 'sh' | 'kn' | 'lc' | 'pm' | 'vc' | 'ws' | 'sm' | 'st' | 'sa' | 'sn' | 'rs' | 'sc' | 'sl' | 'sg' | 'sk' | 'si' | 'sb' | 'so' | 'za' | 'gs' | 'es' | 'lk' | 'sd' | 'sr' | 'sj' | 'sz' | 'se' | 'ch' | 'sy' | 'tw' | 'tj' | 'tz' | 'th' | 'tl' | 'tg' | 'tk' | 'to' | 'tt' | 'tn' | 'tr' | 'tm' | 'tc' | 'tv' | 'ug' | 'ua' | 'ae' | 'gb' | 'us' | 'um' | 'uy' | 'uz' | 'vu' | 've' | 'vn' | 'vg' | 'vi' | 'wf' | 'eh' | 'ye' | 'zm' | 'zw': Two-letter ISO 3166-1 alpha-2 country code to localize results to a specific country (maps to Google's `gl` parameter). Example: "us", "gb", "de". - `languages` union: Languages to return results in, as BCP 47 language codes such as `en` or `de`, or "all" for any language. Defaults to "all". Example: ["en", "de"]. - 'all' - string[] - `queryFanout` boolean: Currently has no effect. - `markdownOptions` object, nullable: Inline Markdown scraping for each result. Set `enabled: true` to activate. - `enabled` boolean: Scrape each result to Markdown. Adds 1 credit per result with Markdown. - `includeLinks` boolean: Keep hyperlinks in the Markdown. - `includeImages` boolean: Emit image references in the Markdown. - `shortenBase64Images` boolean: Truncate inline base64 image payloads to keep responses small. - `useMainContentOnly` boolean: Strip nav, header, footer, and sidebar — keep only the primary article content. - `pdf` object: PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. - `shouldParse` boolean: Parse PDF URLs. When false, PDF results are skipped with WEBSITE_ACCESS_ERROR. - `start` integer: First 1-based PDF page to parse. - `end` integer: Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start. - `includeFrames` boolean: Render iframe contents into the Markdown. - `maxAgeMs` integer, nullable: Maximum cache age in milliseconds for result page content. Defaults to 180 days (15552000000 ms) when Markdown is requested, or 365 days (31536000000 ms) when only highlights are requested. Explicit values override either default. Maximum: 365 days. Set to 0 to force a fresh scrape. - `waitForMs` integer, nullable: Extra wait after page load before rendering, in ms (0–30000). Useful for JS-heavy pages. - `timeoutOpts` ScrapeTimeout: Request deadline and what to return when it passes. - `milliseconds` integer, required: Deadline in milliseconds. - `behavior` 'fail' | 'return-partial': "fail" returns 408 at the deadline. "return-partial" returns available results; inspect the response’s partial flag. "return-partial" requires at least 5000 ms. - `highlightsOptions` object, nullable: Passages from each result page that are relevant to the query. Pages are read with the `markdownOptions` settings. - `enabled` boolean: Return relevant passages for each result. Adds 1 credit per 10 results. - `maxCharacters` integer: Maximum combined length of passages per result. - `descriptionMaxCharacters` integer, nullable: Maximum length of each result's `description`, in characters. - `timeoutOpts` PartialTimeout: Request deadline and what to return when it passes. - `milliseconds` integer, required: Deadline in milliseconds. - `behavior` 'fail' | 'return-partial': "fail" returns 408 at the deadline. "return-partial" returns available results; inspect the response’s partial flag. - `zdr` 'enabled' | 'disabled': `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. - `tags` string[]: Labels for filtering usage in the dashboard. ## Response `200` Search succeeded. Results are ordered by relevance. - object - `partial` boolean: True when timeoutOpts.behavior=return-partial returned the usable results collected before the deadline. Partial collections are not cached as complete results. - `results` object[], required - `url` string, required: Canonical result URL. - `title` string, required: Page title. - `description` string, required: Snippet excerpt from the page. Empty string when the search provider does not supply a snippet. - `relevance` 'high' | 'medium' | 'low', required: Relevance to the original query. - `markdown` object, required: Markdown scrape status and content for this result. - `finalDOMState` 'loaded' | 'still-loading': `loaded`, or `still-loading` when capture ended before the page finished loading. - `markdown` string, nullable, required: GFM Markdown of the page. Null unless markdownOptions.enabled is true and scraping succeeded. - `code` 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'WEBSITE_BLOCKED' | 'ERROR', required: Per-result scrape outcome. Inspect this before reading `markdown`. - `highlights` object, required: Highlights status and passages for this result. - `highlights` string[], nullable, required: Passages relevant to the query, in page order. Null unless highlightsOptions.enabled is true and the page was read. - `code` 'SUCCESS' | 'NOT_REQUESTED' | 'TIMEOUT' | 'CONTENT_TOO_LARGE' | 'WEBSITE_ACCESS_ERROR' | 'WEBSITE_BLOCKED' | 'ERROR', required: Per-result highlights outcome. Inspect this before reading `highlights`. - `query` string, required: Echo of the original query (useful when fanout was enabled). - `cache_metadata` CacheMetadata, required: Whether this response came from cache. - `status` 'hit' | 'miss' | 'zdr', required: Whether the response was served from cache, required fresh work, or honored zero-data-retention cache bypass. - `age_ms` integer, required: Age of the cached data in milliseconds. Zero for miss and zdr responses. - `key_metadata` KeyMetadata: Credits this request used and your remaining balance. - `credits_consumed` integer, required: Credits charged for this request. - `credits_remaining` integer, required: Credits remaining for your organization. - `request_id` string, uuid, required: Unique ID of this request, also in `X-Request-Id`. Include it when contacting support. ## Other responses - `400`: Bad request - Invalid parameters - `401`: Missing, invalid, or disabled API key. - `402`: Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401. - `403`: API key permissions or organization settings do not allow this request. - `408`: Request timeout - `429`: Rate limit exceeded. Organization concurrency rejections include structured error_data and subscription settings; follow Retry-After before retrying. - `500`: Internal server error ## Changes - **2026-10-21** `61627728926b`: 3 warning - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `401` - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `402` - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `403` - **2026-10-19** `4ddcf49b9fe5`: 4 info - added the non-success response with the status `402` - added the optional property `error_data` to the response with the `401` status - added the optional property `error_data` to the response with the `403` status - added the optional property `error_data` to the response with the `429` status - **2026-10-17** `935463eb965e`: 1 info - added the new optional request property `languages` - **2026-10-16** `2125f3e94e52`: 1 info - endpoint added [Operation history](https://skmtc.dev/context/apis/brand-api/changes/web/search/post.md) --- [API](https://skmtc.dev/context/apis/brand-api.md) · [All operations](https://skmtc.dev/context/apis/brand-api/llms.txt) · [OpenAPI document](https://skmtc.dev/context/apis/brand-api/revisions/9e2ab7841fb1?raw)