Query Yandex Search Results

yandex-search-api parses the Yandex search results page through the Yandex Cloud Search API v2, in synchronous and asynchronous modes, with a result cache. Its main feature is smart snippets (infocontexts): instead of a link and a two-sentence snippet, the API returns a roughly 500-token fragment of the found page, relevant to the query and quoting the source document directly - enough to answer from without fetching and parsing the page separately, which is the reason this skill gets installed in an agent at all. Smart snippets are enabled by default with no separate script; the extracted text is written to cache/results/<hash>.md rather than printed to stdout, since 20 documents at roughly 500 tokens each would overflow a sandbox's output buffer and fail silently - the script prints only a per-document index, and the text is read back from the cache file with Read or grep.

Three hard limits shape command choice: smart snippets work only in synchronous mode (web_search_async.sh never returns them); only with SEARCH_TYPE_RU (any other search type runs the query but returns no snippets, and the skill says so); and never more than 20 documents (requesting more than 20 via --results gets half as many back at the same price, so the skill clamps the value itself). Smart snippets also cost about three times a plain synchronous request. When only positions and domains are needed, --no-snippets (or search.smart_snippets.enabled: false in config) skips them.

Authentication needs a Yandex Cloud service account with the search-api.webSearch.user role, via either an IAM-authorized JSON key or a service-account API key (auth.mode: "api_key" plus YANDEX_AI_API_KEY); existing IAM configurations keep working unchanged. Before any search, the workflow requires resolving the region first: if the user names a city, search_region.sh --name "<city>" resolves its ID automatically; if the region is unclear from context, the skill must ask and wait for an answer rather than guessing, and must clarify an ambiguous case like "Moscow city" versus "Moscow region." Search mode comes from config.json's search.mode (default sync) and is not something to ask about, except that smart snippets always force sync mode and SEARCH_TYPE_RU, since neither is available in the async API or other search locales.

Its scripts: iam_token_get.sh generates or refreshes a cached IAM token from the service-account key (only needed for auth.mode: iam); web_search_sync.sh runs one query at a time with immediate results and is the only mode that supports smart snippets, accepting a single --query or a --file of one query per line; web_search_async.sh submits many queries as async operations, polls for completion, and supports --resume to continue from cache/ops/ after a timeout or interrupt without duplicating work - it is about 16x cheaper than synchronous search and about 50x cheaper than smart-snippet search, but returns only links and short snippets, never page extracts; regions_tree.sh lists common region IDs; and search_region.sh finds a region ID by name.

Each result carries a position, title, URL, a short snippet (up to 300 characters), a domain, and an extract field holding the smart-snippet page fragment (empty when none was returned). Results are cached as <hash>.md (a readable pack of title/URL/extract per document), <hash>.raw (the original response body - XML for a plain search, JSON when smart snippets are requested) and <hash>.json (a normalized parsed array), keyed by the first 12 characters of an MD5 hash of the query text. Offline tests (scripts/tests/run.sh) exercise request-body construction, both response formats, cache-pack rendering and CLI flag parsing with no network or service account required, and YSA_DRY_RUN=1 prints the request body without spending anything.

Pricing per 1,000 queries (with VAT): daytime synchronous searches cost 488 rubles, nighttime synchronous (00:00-07:59 UTC+3) 366 rubles, daytime asynchronous 30.5 rubles, and RU-region smart-snippet searches 1,500 rubles - about three times a plain synchronous request.

It authenticates against Yandex Cloud via a service account (IAM key or API key) that needs the search-api.webSearch.user role, and calls the Yandex Cloud Search API v2 directly through bundled shell scripts, with no other external service dependency. A 403 response means that role is missing from the service account; a full result set that shows 0 snippets in the "Total: N, with snippets: M" line usually means the smart-snippet flag isn't enabled for the folder ID (check the raw response for XML instead of JSON), or the search type was overridden away from SEARCH_TYPE_RU.

It suits agents and workflows that need to search the Russian-language web via Yandex and ground an answer in the actual content of the results, not just their links.

Use it when an agent needs to search Yandex and answer from the actual content of found pages rather than just their links, or needs bulk positional/link results cheaply via async search instead.

Input is a search query (or a file of one-per-line queries) and a resolved region ID (ambiguous city/region names must be clarified with the user first, never guessed). Output is a cached per-query result set keyed by a hash of the query text.