Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Getting started with Yandex Search API

Written by
Updated at November 27, 2025

Yandex Search API is fully integrated into the Yandex Cloud ecosystem and alongside the API key authentication supports the more secure short-lived IAM token authentication.

You can run queries to Yandex Search API using the Yandex Cloud ML SDK, REST API, and gRPC API. The search results you get depend on the parameters specified in your query.

For Yandex Search API prices, see Yandex Search API pricing policy.

Getting started

Sign up for Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or create a new account.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure.

Learn more about clouds and folders here.

Get your cloud ready

To use the examples:

  1. Create a service account and assign the search-api.webSearch.user role to it.

  2. Get and save the service account's API key with yc.search-api.execute for its scope.

    The following examples use API key authentication. Yandex Cloud ML SDK also supports IAM token and OAuth token authentication. For more information, see Authentication in Yandex Cloud ML SDK.

    Note

    If you are using Windows, we recommend installing the WSL shell first and using it to proceed.

  3. Install Python 3.10 or higher.

  4. Install Python venv to create isolated virtual environments in Python.

  5. Create a new Python virtual environment and activate it:

    python3 -m venv new-env
source new-env/bin/activate

  6. Use the pip package manager to install the ML SDK library:

    pip install yandex-cloud-ml-sdk
  1. Create a service account you will use to send requests to Yandex Search API.
  2. Assign the search-api.webSearch.user role to the service account you created.
  3. Create an API key for the service account with yc.search-api.execute for its scope.
  4. To use the examples, you should additionally install cURL and jq.

The following examples use API key authentication. To use an IAM token for authentication, edit the Authorization header in the request examples. For more information, see API authentication.

In the provided examples, requests to Yandex Search API are REST API requests. For sample gRPC API request, see Performing text search queries in deferred mode.

Send a search query

In the example, the request returns a page of search results for the coffee machine query in HTML and XML formats.

To run a search query using Yandex Search API:

  1. Create a file named web-search.py and paste the following code into it:

    #!/usr/bin/env python3

from __future__ import annotations

from yandex_cloud_ml_sdk import YCloudML

from yandex_cloud_ml_sdk.search_api import (
    FamilyMode,
    FixTypoMode,
    GroupMode,
    Localization,
    SearchType,
    SortMode,
    SortOrder,
)

import pathlib

USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 YaBrowser/25.2.0.0 Safari/537.36"

search_query = "coffee machine"

formats = ["xml", "html"]


def main() -> None:

    sdk = YCloudML(
        folder_id="<folder_ID>",
        auth="<API_key>",
    )
    sdk.setup_default_logging("error")

    search = sdk.search_api.web(
        search_type="ru",
        user_agent=USER_AGENT,
    )

    for format in formats:

        print(f"Saving results in the {format.upper()} format:")
        for page in range(0, 3):
            operation = search.run_deferred(search_query, format=format, page=page)
            search_result = operation.wait(poll_interval=1)
            output_filename = (
                str(pathlib.Path(__file__).parent)
                + "/"
                + "page_"
                + str(page + 1)
                + "."
                + format
            )
            file = open(output_filename, "a")
            file.write(search_result.decode("utf-8"))
            print(f"Page {page} saved to file {output_filename}")
            file.close()
        print()


if __name__ == "__main__":
    main()

    Where:

    For more information on query parameters, see Performing text search queries in deferred mode.

  2. Run the file you created:

    python3 web-search.py

    As a result of execution, the code will save the first three pages of search results for the coffee machine query in the current directory in XML and HTML formats:

    Saving results in the XML format:
Page 0 saved to file /Users/MyUser/Desktop/page_1.xml
Page 1 saved to file /Users/MyUser/Desktop/page_2.xml
Page 2 saved to file /Users/MyUser/Desktop/page_3.xml

Saving results in the HTML format:
Page 0 saved to file /Users/MyUser/Desktop/page_1.html
Page 1 saved to file /Users/MyUser/Desktop/page_2.html
Page 2 saved to file /Users/MyUser/Desktop/page_3.html

  1. Send a search query:

    1. Create a request body file (e.g., body.json) with the ID of the folder you are going to use for Yandex Search API in the folderId field:

      body.json

      {
    "query": {
      "searchType": "SEARCH_TYPE_RU",
      "queryText": "coffee machine"
    },
    "folderId": "<folder_ID>",
    "responseFormat": "FORMAT_HTML",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 YaBrowser/25.2.0.0 Safari/537.36"
}

      body.json

      {
    "query": {
      "searchType": "SEARCH_TYPE_RU",
      "queryText": "coffee machine"
    },
    "folderId": "<folder_ID>",
    "responseFormat": "FORMAT_XML",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 YaBrowser/25.2.0.0 Safari/537.36"
}

      For more information about the request body parameters, see API request body format.

    2. Send your HTTP request by specifying the API key created earlier and the path to the request body file:

      curl \
  --request POST \
  --header "Authorization: Api-Key <API_key>" \
  --data "@body.json" \
  "https://searchapi.api.cloud.yandex.net/v2/web/searchAsync"

      Result:

      {
"done": false,
"id": "sprqjo0kf40j********",
"description": "WEB search async",
"createdAt": "2025-05-05T18:10:44Z",
"createdBy": "ajegtlf2q28a********",
"modifiedAt": "2025-05-05T18:10:44Z"
}

      This will return the Operation object ID (id field value) by which you can retrieve the result of the operation. Save the ID for later.

  2. Wait until Yandex Search API executes the request and generates a response. This may take from a few minutes to a few hours.

    To make sure your search query was executed successfully, send the following HTTP request:

    curl \
  --request GET \
  --header "Authorization: Api-Key <API_key>" \
  https://operation.api.cloud.yandex.net/operations/<request_ID> \
  > result.json

    Where:

    • <API_key>: API key you created earlier.
    • <request_ID>: The Operation object ID you saved in the previous step.

    The response will be saved to the result.json file. Open the file to make sure its done field is set to true, and the response field contains the result of the search query. The result in the response field is saved in Base64 encoding.

  3. Decode the result. To do this, run this command:

    echo "$(< result.json)" | \
  jq -r .response.rawData | \
  base64 --decode > result.html

    The HTML response to the query will be saved to a file named result.html.

    echo "$(< result.json)" | \
  jq -r .response.rawData | \
  base64 --decode > result.xml

    The XML response to the query will be saved to a file named result.xml.

See also

Next
All guides