--- title: "Perform a web search" method: POST path: "/search" tags: ["Search"] --- # Perform a web search `POST /search` ## Request - Base URL: `https://kagi.com/api/v1` - URL: `https://kagi.com/api/v1/search` - Auth: HTTP bearer ## Request body - object: Used to upload the search query - `query` string, required: Search query to run. - `workflow` 'search' | 'images' | 'videos' | 'news' | 'podcasts': Type of results to return. - `format` 'json' | 'markdown': **(EXPERIMENTAL)** Format to serialize the API response as. The exact contents and structure of markdown output is still being worked on - please send your feedback! - `lens_id` string: Lens to apply to the search. Can be a built-in lens's identifier or a lens ID as shown on https://kagi.com/settings/lenses when a lens is set to be shareable. Can be just the ID portion of the URL (`https://kagi.com/lenses/ID`) or the full URL. - `lens` object: Inline description of a lens to apply to the search. Options supplied by the lens take precedence over those supplied by the user in their search terms (e.g., `site:` operators), allowing you to restrict the scope of the search to return more relevant results in specific applications. - `sites_included` string[]: Search only these domains. - `sites_excluded` string[]: Exclude these domains from the search. - `keywords_included` string[]: Return only results containing these keywords. - `keywords_excluded` string[]: Exclude results containing these keywords. - `file_type` string: A specific file type to search for. (e.g., `pdf`) - `time_after` string, date: Filters for web pages that have been updated or published *after* the given date. - `time_before` string, date: Filters for web pages that have been updated or published *before* the given date. - `time_relative` 'day' | 'week' | 'month': Filters for web pages that have been updated or published in the given interval, relative to today's date. - `search_region` string: Requests results localized to a specific region. Can be any valid [ISO-3166-1 Alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements), or the special value `no_region`, that will try to get the most general results possible. - `timeout` number: Number of seconds to allow for collecting search results. Lower values will return results more quickly, but may be lower quality or inconsistent between calls. If omitted, will use the latest recommended value by Kagi. - `page` integer: Page number for paginated results. Must be between 1 and 10. - `limit` integer: Maximum number of results to return. Must be between 1 and 1024. **NOTE:** This does not change the amount of results requested, it only limits the maximum amount returned. If omitted, the API always gives you the most results we can get in a single pass. - `filters` object: Filters to apply to search results for more targeted queries. **NOTE:** Any parameter here that overlaps with lenses will take priority over the lens. - `region` string: Filter results to a specific region using an ISO 3166-1 Alpha-2 country code. See https://help.kagi.com/api/regions for supported codes. - `after` string, date: Filter for results published or updated after this date. - `before` string, date: Filter for results published or updated before this date. - `extract` object: Configuration for extracting page content from search results. When provided, the API will fetch and extract the content from the specified number of result pages. The resulting page markdown will update the value of the `snippet` field on the respective result item. **NOTE:** Use of this option incurs additional cost, billed at your account's rate for the Extract API based on the number of units requested. You will not be charged if there were no results to extract. - `count` integer: Number of search results to extract content from. Must be between 1 and 10. - `timeout` number: Timeout in seconds for extraction of each page. If omitted, uses the default timeout. This time budget is in addition to the allocated top-level search timeout, so that you can control both independently. - `safe_search` boolean: Whether safe search is enabled, omitting potentially NSFW content. - `personalizations` object: Personalization rules to customize search result ranking. Allows specifying domain biases and regex-based replacements. - `domains` object[]: Domain-level personalization rules (maximum 1000 rules). Each rule can boost or lower the ranking of results from specific domains. - `domain` string, required: Domain pattern to personalize (e.g., "example.com"). Can also be a tld suffix like ".co.uk". - `kind` 'block' | 'lower' | 'raise' | 'pin', required: Handling mode for this domain pattern - `regexes` object[]: Regex-based personalization rules (maximum 1000 rules, max 1000 bytes per pattern). - `regex` string: The regex pattern to match. - `replacement` string: The replacement string to apply when the pattern matches. Will preserve paths and query parameters if not overwritten. You can refer to capture groups with "$1", "$2", etc. ## Response `200` Success - object: A response with a description and results references used - `meta` Meta: This object is subject to change as it is provided for debugging purposes. Fields may be added or removed as required. Don't build any hard dependancies on any of this data. - `trace` string: Trace ID that can be used to debug individual API requests. Provide this, if needed, when contacting Kagi support. - `node` string: The hostname of the node that fulfilled the request. - `ms` integer: how long the request took to fulfill, excluding round trip to the client. - `data` object: Holds all the search results for the query specified. As results have different types and sources, they are separated into different fields within this object. For example image results are stored under `data.image` while news results are stored under `data.news`. All results will have the same main structure, but additional data might be stored under the `data.{name}[].props` path. Please look at each different type of result for more information about this. - `search` SearchResult[]: Contains all search results for html pages or websites. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects ``. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `image` SearchResult[]: Contains all search results for images. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `video` SearchResult[]: Contains all search results for videos. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `podcast` SearchResult[]: Contains all search results for podcasts. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `podcast_creator` SearchResult[]: Contains all search results for creators of podcasts. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `news` SearchResult[]: Contains all search results for news articles. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `adjacent_question` SearchResult[]: Contains results that are obtained by searching for slightly different queries. These questions are stored under the `props.question` path. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `direct_answer` SearchResult[]: If the search query was a math equation, or unit conversions, things that can be answered quickly, the result will be in here. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `interesting_news` SearchResult[]: Contains news results from publishers collected and stored in Kagi's news index. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `interesting_finds` SearchResult[]: Contains small web results from publishers collected and stored in Kagi's small web index. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `infobox` SearchResult[]: Contains detailed summary and tabulated information about a person, place, or thing. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `code` SearchResult[]: Contains all search results that link to code resources or repositories. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `package_tracking` SearchResult[]: If the search query was a package tracking number, the correct package tracking website should be present in this collection. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `public_records` SearchResult[]: Contains all search results for public records, such as government documents or public court records. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `weather` SearchResult[]: Contains all search results for the current weather. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `related_search` SearchResult[]: Contains a list of searches that are related to the current search, and may help narrow down the results. - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `listicle` SearchResult[]: Contains all search results that are lists of things. Results with titles like "5 things you didn't know about...", or "10 of the best headphones". - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata - `web_archive` SearchResult[]: Contains all search results for archived websites that may not be available anymore - `url` string, required: The location of the result. This is the direct URL to the resource that matches the query - `title` string, required: This is the title of the resource. For HTML documents, it reflects `<title>`. For videos, it is the name that would be displayed on the video site. - `snippet` string: A short summary of the contents of the resource - `time` string: The date when the resource was created or last updated. - `image` object: An image that goes with the main resource. It could be a video's thumbnail or an HTML document's main image. - `url` string, required: This is a URL that links directly to the image that goes with the resources. - `height` integer: The height of the image. - `width` integer: The width of the image. - `props` object: Holds arbitrary result metadata ## Other responses - `400`: Invalid request parameters - `401`: Access token is missing or invalid - `403`: Forbidden - IP address not authorized - `429`: Rate limited or usage limit exhausted - `500`: Internal server error --- [API](https://skmtc.dev/kagi/apis/kagi-api.md) · [All operations](https://skmtc.dev/kagi/apis/kagi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kagi/apis/kagi-api/revisions/d9c0ffdb4eaa?raw)