Yandex Cloud
Search
Contact UsGet started
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • AI for business
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Center for Technologies and Society
    • Yandex Cloud Partner program
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
© 2025 Direct Cursus Technology L.L.C.
Yandex Search API
  • Getting started
    • Overview
    • Text search
    • XML response
    • HTML response
    • Generative response
    • Image search
    • Quotas and limits
  • Access management
  • Pricing policy
  • Audit Trails events
  • Release notes

In this article:

  • API request body format
  • Sending a request via the API
  • Sending a request via Yandex Cloud ML SDK
  • Generative response
  • Response features
  1. Concepts
  2. Generative response

Generative response

Written by
Yandex Cloud
Improved by
magician-neko
Updated at November 27, 2025
  • API request body format
  • Sending a request via the API
  • Sending a request via Yandex Cloud ML SDK
  • Generative response
  • Response features

You can use Yandex Search API text search together with YandexGPT's generative AI capabilities to get a single concise and coherent generative response to your query, to generate which the neural network analyzes relevant Yandex Search API text search results across specified websites. The response can be generated in Russian, Kazakh and Uzbek. The generation language depends on the search type and query language.

By default, you can send no more than one synchronous query per second to get a generative response. For more information about Yandex Search API limits, see Quotas and limits in Yandex Search API.

You need the search-api.webSearch.user role to run queries.

For more information on the pricing of generative responses to queries, see Yandex Search API pricing policy.

API request body formatAPI request body format

The names of the request body fields are different in REST API and gRPC API: the former uses camelCase, while the latter, snake_case.

Each query seeking a generative response must contain the following request body in JSON format:

REST API
gRPC API
{
  "messages": [
    {
      "content": "<message_1_text>",
      "role": "ROLE_USER"
    },
    {
      "content": "<model_2_response>",
      "role": "ROLE_ASSISTANT"
    },
    {
      "content": "<message_3_text>",
      "role": "ROLE_USER"
    },
    {
      "content": "<model_4_response>",
      "role": "ROLE_ASSISTANT"
    },
    ...
    {
      "content": "<message_n_text>",
      "role": "ROLE_USER"
    }
  ],
  "site": {
    "site": [
      "<website_1_address_for_search>",
      "<website_2_address_for_search>",
      ...
      "<website_5_address_for_search>"
    ]
  },
  "host": {
    "host": [
      "<host_1_for_search>",
      "<host_2_for_search>",
      ...
      "<host_5_for_search>"
    ]
  },
  "url": {
    "url": [
      "<page_1_for_search>",
      "<page_2_for_search>",
      ...
      "<page_10_for_search>"
    ]
  },
  "folderId": "<folder_ID>",
  "fixMisspell": true|false,
  "enableNrfmDocs": true|false,
  "searchFilters": [
    {
      "date": "<document_update_date>",
      "lang": "<document_language>",
      "format": "<document_format>"
    }
  ]
  "searchType": "string",
  "getPartialResults": true|false,
  "metadata": {
    "fields": "object"
  }
}

Where:

  • messages: Single search query or a search query with context in the form of chat with the model. It is specified as an array of objects, each one containing two elements:

    • content: Text of a user message or model's response (depending on the role value).
    • role: Message sender's role. The possible values are:
      • ROLE_USER: Means the message is sent by the user, and the content field contains the user's query.
      • ROLE_ASSISTANT: Means the message is sent by the model, and the content field contains the model's response.

    For more information about the YandexGPT chat mode, see How to build a chat with the Responses API.

  • Set the search scope in the site, host, and url fields. Note that the site, host, and url fields are mutually exclusive; you can only set one of them. If neither of these fields is set, the search will be performed across the entire Yandex search index.

    • site: Restricts the search to a specific array of websites. Not more than 5 websites per search.

      For example, for the yandex.cloud website, the search will target all *.yandex.cloud/* documents, i.e., the results will include pages with the following URLs:

      • yandex.cloud/
      • subdomain.yandex.cloud/
      • yandex.cloud/path/
      • subdomain.yandex.cloud/path/

      You can use the site field to specify the exact path to the search area, e.g., https://yandex.cloud/en/docs.

    • host: Restricts the search to a specific array of hosts. Not more than 5 hosts per search.

      For example, for the yandex.cloud/ host, the search will target all yandex.cloud/* documents, i.e., the results will include pages with the following URLs:

      • yandex.cloud/
      • yandex.cloud/path/

      Unlike site-based restrictions, host-based restrictions do not apply to subdomains. You also cannot provide a specific path to the search area in the host field.

    • url: Restricts the search to a specific array of pages, e.g., https://yandex.cloud/en/docs/serverless-containers/concepts/container and https://yandex.cloud/en/docs/container-registry/concepts/docker-image. Not more than 10 pages per search.

  • folderId: Folder ID.

  • fixMisspell: This parameter enables checking the query text for typos. If the parameter is set, the query text is checked for typos before it is sent. If there are typos, the fixedMisspellQuery field is added to the response, containing the fixed query text that was sent to the model. This is an optional parameter. The possible values are true or false.

  • enableNrfmDocs: This parameter determines whether search results will include documents which are not directly accessible from the home page. It only applies if the search scope is set by the site parameter. For example, if you want the results to include a page that is not accessible through any of the links on the home page, set enableNrfmDocs to true. This is an optional parameter. The possible values are true or false.

  • searchFilters: Additional text to add to each query. It is used to provide the date:, mime:, and lang: search operators. For example, if you provide "date": ">20250101", the query response will only return documents updated after January 1, 2025. This is an optional parameter. The date, lang, and format fields are mutually exclusive: you can only provide one of them in the request body.

  • searchType: Search type, affects the search area and response language. The possible values are:

    • SEARCH_TYPE_RU: For the Russian search type. The response will be generated in Russian.
    • SEARCH_TYPE_KK: For the Kazakh search type. If your query is in Russian, the response will be generated in Russian; if your query is in Kazakh, the response will be generated in Kazakh.
    • SEARCH_TYPE_UZ: For the Uzbek search type. If your query is in Russian, the response will be generated in Russian; if your query is in Uzbek, the response will be generated in Uzbek.
  • getPartialResults: Decides whether to send intermediate response generation results or to wait for the final generation results and send the whole response. This is an optional parameter. The possible values are true or false. The default value is false.

  • metadata: Additional search parameters. This is an optional parameter.

Request body example:
{
  "messages": [
    {
      "content": "What is containerization and how is it implemented in Yandex Cloud?",
      "role": "ROLE_USER"
    }
  ],
  "site": {
    "site": [
        "https://ru.wikipedia.org/wiki/Контейнеризация",
        "https://yandex.cloud/ru/docs/serverless-containers/",
        "https://yandex.cloud/ru/docs/container-registry/"
    ]
  },
  "folderId": "aoevhr118rhc********",
  "fixMisspell": "true",
  "enableNrfmDocs": "true",
  "searchFilters": [
    {
      "date": ">20250101"
    }
  ]
}
{
  "messages": [
    {
      "content": "<message_1_text>",
      "role": "ROLE_USER"
    },
    {
      "content": "<model_1_response>",
      "role": "ROLE_ASSISTANT"
    },
    {
      "content": "<message_2_text>",
      "role": "ROLE_USER"
    },
    {
      "content": "<model_3_response>",
      "role": "ROLE_ASSISTANT"
    },
    ...
    {
      "content": "<message_n_text>",
      "role": "ROLE_USER"
    }
  ],
  "site": {
    "site": [
      "<website_1_address_for_search>",
      "<website_2_address_for_search>",
      ...
      "<website_5_address_for_search>"
    ]
  },
  "host": {
    "host": [
      "<host_1_for_search>",
      "<host_2_for_search>",
      ...
      "<host_5_for_search>"
    ]
  },
  "url": {
    "url": [
      "<page_1_for_search>",
      "<page_2_for_search>",
      ...
      "<page_10_for_search>"
    ]
  },
  "folder_id": "<folder_ID>",
  "fix_misspell": true|false,
  "enable_nrfm_docs": true|false,
  "search_filters": [
    {
      "date": "<document_update_date>",
      "lang": "<document_language>",
      "format": "<document_format>"
    }
  ]
}

Where:

  • messages: Single search query or a search query with context in the form of chat with the model. It is specified as an array of objects, each one containing two elements:

    • content: Text of a user message or model's response (depending on the role value).
    • role: Message sender's role. The possible values are:
      • ROLE_USER: Means the message is sent by the user, and the content field contains the user's query.
      • ROLE_ASSISTANT: Means the message is sent by the model, and the content field contains the model's response.

    For more information about the YandexGPT chat mode, see How to build a chat with the Responses API.

  • Set the search scope in the site, host, and url fields. Note that the site, host, and url fields are mutually exclusive; you can only set one of them. If neither of these fields is set, the search will be performed across the entire Yandex search index.

    • site: Restricts the search to a specific array of websites. Not more than 5 websites per search.

      For example, for the yandex.cloud website, the search will target all *.yandex.cloud/* documents, i.e., the results will include pages with the following URLs:

      • yandex.cloud/
      • subdomain.yandex.cloud/
      • yandex.cloud/path/
      • subdomain.yandex.cloud/path/

      You can use the site field to specify the exact path to the search area, e.g., https://yandex.cloud/en/docs.

    • host: Restricts the search to a specific array of hosts. Not more than 5 hosts per search.

      For example, for the yandex.cloud/ host, the search will target all yandex.cloud/* documents, i.e., the results will include pages with the following URLs:

      • yandex.cloud/
      • yandex.cloud/path/

      Unlike site-based restrictions, host-based restrictions do not apply to subdomains. You also cannot provide a specific path to the search area in the host field.

    • url: Restricts the search to a specific array of pages, e.g., https://yandex.cloud/en/docs/serverless-containers/concepts/container and https://yandex.cloud/en/docs/container-registry/concepts/docker-image. Not more than 10 pages per search.

  • folder_id: Folder ID.

  • fix_misspell: This parameter enables checking the query text for typos. If the parameter is set, the query text is checked for typos before it is sent. If there are typos, the fixed_misspell_query field is added to the response, containing the fixed query text that was sent to the model. This is an optional parameter. The possible values are true or false.

  • enable_nrfm_docs: This parameter determines whether search results will include documents which are not directly accessible from the home page. It only applies if the search scope is set by the site parameter. For example, if you want the results to include a page that is not accessible through any of the links on the home page, set enable_nrfm_docs to true. This is an optional parameter. The possible values are true or false.

  • search_filters: Additional text to add to each query. It is used to provide the date:, mime:, and lang: search operators. For example, if you provide "date": ">20250101", the query response will only return documents updated after January 1, 2025. This is an optional parameter. The date, lang, and format fields are mutually exclusive: you can only provide one of them in the request body.

  • search_type: Search type, affects the search area and response language. The possible values are:

    • SEARCH_TYPE_RU: For the Russian search type. The response will be generated in Russian.
    • SEARCH_TYPE_KK: For the Kazakh search type. If your query is in Russian, the response will be generated in Russian; if your query is in Kazakh, the response will be generated in Kazakh.
    • SEARCH_TYPE_UZ: For the Uzbek search type. If your query is in Russian, the response will be generated in Russian; if your query is in Uzbek, the response will be generated in Uzbek.
  • get_partial_results: Decides whether to send intermediate response generation results or to wait for the final generation results and send the whole response. This is an optional parameter. The possible values are true or false. The default value is false.

  • metadata: Additional search parameters. This is an optional parameter.

{
  "messages": [
    {
      "content": "What is containerization and how is it implemented in Yandex Cloud?",
      "role": "ROLE_USER"
    }
  ],
  "site": {
    "site": [
        "https://ru.wikipedia.org/wiki/Контейнеризация",
        "https://yandex.cloud/ru/docs/serverless-containers/",
        "https://yandex.cloud/ru/docs/container-registry/"
    ]
  },
  "folder_id": "aoevhr118rhc********",
  "fix_misspell": "true",
  "enable_nrfm_docs": "true",
  "search_filters": [
    {
      "date": ">20250101"
    }
  ]
}

Sending a request via the APISending a request via the API

REST API
gRPC API

To send a request via the API, use the search method for GenSearch. Install cURL and jq if needed:

curl \
  --request POST \
  --header "Authorization: Bearer <IAM_token>" \
  --data "@<file_path>" \
  "https://searchapi.api.cloud.yandex.net/v2/gen/search" \
  | jq

Where:

  • <IAM_token>: IAM token of a user or service account with the search-api.webSearch.user role.
  • <file_path>: Path to the file with the request body.

To send a query, use the GenSearchService/Search call. Install gRPCurl and jq if needed:

grpcurl \
  -rpc-header "Authorization: Bearer <IAM_token>" \
  -d @ < <file_path> \
  searchapi.api.cloud.yandex.net:443 yandex.cloud.searchapi.v2.GenSearchService/Search \
  | jq

Where:

  • <IAM_token>: IAM token of a user or service account with the search-api.webSearch.user role.
  • <file_path>: Path to the file with the request body.

Sending a request via Yandex Cloud ML SDKSending a request via Yandex Cloud ML SDK

To send a request for a generative response via Yandex Cloud ML SDK, run the following Python code. This example illustrates the key aspects of using ML SDK to get a generative response:

#!/usr/bin/env python3

from __future__ import annotations

import pprint

from yandex_cloud_ml_sdk import YCloudML


def main() -> None:

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

    search = sdk.search_api.generative(
        # You can use only one of the three params: site, host, or url
        site=["yandex.cloud", "yandex.ru"],
        # host=['yandex.cloud/', 'yandex.ru/'],
        # url=['https://yandex.cloud/ru/docs/serverless-containers/concepts/container', 'https://yandex.cloud/ru/docs/container-registry/concepts/docker-image'],
        fix_misspell=True,
        enable_nrfm_docs=True,
        search_filters=[
            {"date": ">20250101"},
            {"lang": "ru"},
            {"format": "pdf"},
        ],
    )

    # You can pass a string as a query
    search_result = search.run("Yandex Cloud generative Search API params")

    # You can examine the search_result structure via pprint
    # to get to know how to work with it:
    pprint.pprint(search_result)
    print()

    queries = [
        # You can also pass a {'text', 'role'} dict like in the completions models
        {"text": "Gen search api params", "role": "user"},
        "With examples",
    ]

    # And you can pass an array of any allowed types
    search_result = search.run(queries)  # type: ignore[arg-type]
    print(search_result.text)
    print()

    # Also search result itself could be used as one of the queries for a better context
    queries.append(search_result)  # type: ignore[arg-type]
    queries.append("Get me more examples of how to use Generative Search API with gprc")

    search_result = search.run(queries)  # type: ignore[arg-type]
    print(search_result.text)
    print()


if __name__ == "__main__":
    main()

Where:

  • <folder_ID>: ID of the folder in which the service account was created.

  • <API_key>: Service account API key you got earlier required for authentication in the API.

    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.

Provide the search query text in the .run method and use the relevant search_api.generative object properties to set the parameters of your search:

  • The site, host, and url properties define the search scope. Note that the site, host, and url properties are mutually exclusive; you can only set one of them. If neither of these fields is set, the search will be performed across the entire Yandex search index.

    • site: Restricts the search to a specific array of websites. Not more than 5 websites per search.

      For example, for the yandex.cloud website, the search will target all *.yandex.cloud/* documents, i.e., the results will include pages with the following URLs:

      • yandex.cloud/
      • subdomain.yandex.cloud/
      • yandex.cloud/path/
      • subdomain.yandex.cloud/path/

      In the site property, you can specify the exact path to the search area, e.g., https://yandex.cloud/en/docs.

    • host: Restricts the search to a specific array of hosts. Not more than 5 hosts per search.

      For example, for the yandex.cloud/ host, the search will target all yandex.cloud/* documents, i.e., the results will include pages with the following URLs:

      • yandex.cloud/
      • yandex.cloud/path/

      Unlike site-based restrictions, host-based restrictions do not apply to subdomains. You also cannot provide a specific path to the search area in the host property.

    • url: Restricts the search to a specific array of pages, e.g., https://yandex.cloud/en/docs/serverless-containers/concepts/container and https://yandex.cloud/en/docs/container-registry/concepts/docker-image. Not more than 10 pages per search.

  • fix_misspell: This parameter enables checking the query text for typos. If the parameter is set, the query text is checked for typos before it is sent. If there are typos, the fixed_misspell_query field is added to the response, containing the fixed query text that was sent to the model. This is an optional parameter. The possible values are true or false.

  • enable_nrfm_docs: This parameter determines whether search results will include documents which are not directly accessible from the home page. It only applies if the search scope is set by the site parameter. For example, if you want the results to include a page that is not accessible through any of the links on the home page, set enable_nrfm_docs to true. This is an optional parameter. The possible values are true or false.

  • search_filters: Additional text to add to each query. It is used to provide the date:, mime:, and lang: search operators. For example, if you provide "date": ">20250101", the query response will only return documents updated after January 1, 2025. This is an optional parameter.

For the ML SDK library source code and use cases, visit this GitHub repository. You can learn more about Yandex Cloud ML SDK in this AI Studio guide.

Generative responseGenerative response

Yandex Search API returns a JSON format response with the following syntax:

Note

The response contains no required fields. It may not return a field if there is no relevant data.

REST API
gRPC API
{
  "message": {
    "content": "<response_text>",
    "role": "ROLE_ASSISTANT"
  },
  "sources": [
    {
      "used": false|true,
      "url": "<link_to_found_document_1>",
      "title": "<title_of_found_document_1>"
    },
    {
      "used": false|true,
      "url": "<link_to_found_document_2>",
      "title": "<title_of_found_document_2>"
    },
    ...
    {
      "used": false|true,
      "url": "<link_to_found_document_n>",
      "title": "<title_of_found_document_n>"
    }
  ],
  "searchQueries": [
    {
      "text": "<query_1_text>",
      "reqId": "<query_1_ID>"
    },
    {
      "text": "<query_2_text>",
      "reqId": "<query_2_ID>"
    },
    ...
    {
      "text": "<query_n_text>",
      "reqId": "<query_n_ID>"
    },
  ],
  "isAnswerRejected": false|true,
  "isBulletAnswer": false|true,
  "fixedMisspellQuery": "<fixed_query_text >"
}

Where:

  • message.content: Text of the generative response. The footnotes within the text refer to sources, the list and order of which are given in the sources field.

  • sources: Array of source documents that were found during the query, could be used by YandexGPT as data sources when forming the response, and can be footnoted in the message.content field. Each source document contains the following fields:

    • used: Indicates whether the document was used to generate the response. The possible values are true or false.
    • url: Document URL.
    • title: Document title. It may be missing from the results if the website owner did not define the page header.
  • searchQueries: List of additional search queries sent by the generative model to the search engine. Each query contains the following fields:

    • text: Search query text.
    • reqId: Yandex Search API unique query ID.
  • isAnswerRejected: Indicates the model's refusal to provide a response for ethical reasons:

    • false: Model has returned a response.
    • true: Model has refused to return a response.
  • isBulletAnswer: Indicates a bullet response where the model cannot give a proper response and suggests a set of bullets with various information:

    • false: Model gave a good answer.
    • true: Model suggested a set of bullets.
  • fixedMisspellQuery: Fixed query text. This parameter is optional. It appears in the response only if you provide fixMisspell in the request body and typos were found in the query text.

Here is an example of a generative response with website limitation:
[
  {
    "message": {
      "content": "**Containerization** (OS-level virtualization) is a **virtualization method** 
      in which the OS kernel manages several isolated user-space instances 
      instead of a single one. [1] These instances (containers or zones) are identical
      to a separate OS instance in terms of the processes running inside them. [1] vCPU 
      provides complete container isolation, so applications from different containers 
      have no impact on one another. [1]\n\n**In Yandex Cloud, containerization is implemented with the help of 
      Yandex Serverless Containers**. [5][6] A container allows you to run an application 
      contained in a Docker image, in Yandex Cloud. [6] \n\n**Some aspects of containerization in 
      Yandex Cloud:**\n\n* **Creating a container revision**. [6] You can only create a container revision 
      from a Docker image uploaded to a registry in Yandex Container Registry. [6] Other registries are not 
      supported. [6] The revision contains all the information you need to run the container. [6]\n* 
      **Invoking a container**. [6] Once you have created a revision, you can invoke the container via HTTPS 
      using a trigger or the Yandex API Gateway extension. [6]\n* **Scaling a container**. [6] If 
      the container is invoked faster than the instance can process the request, the service scales the container 
      by running additional instances of it. [6] This enables concurrent request 
      processing. [6]\n* **Provisioned instances**. [6] A provisioned instance 
      is a container instance that is guaranteed not to have a cold start when you run it. [6]",
      "role": "ROLE_ASSISTANT"
    },
    "sources": [
      {
        "used": false,
        "url": "https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D1%82%D0%B5%D0%B9%D0%BD%D0%B5%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F",
        "title": "Containerization (Wikipedia)"
      },
      {
        "used": true,
        "url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/functions-framework-to-container",
        "title": "Developing functions in Functions Framework and deploying them to Yandex Serverless Containers | Yandex Cloud documentation"
      },
      {
        "used": false,
        "url": "https://yandex.cloud/ru/docs/container-registry/",
        "title": "Yandex Container Registry | Yandex Cloud documentation"
      },
      {
        "used": false,
        "url": "https://yandex.cloud/ru/docs/container-registry/concepts/docker-image",
        "title": "Docker image. What is it and how does it work? | Yandex Cloud documentation"
      },
      {
        "used": false,
        "url": "https://yandex.cloud/ru/docs/serverless-containers/operations/",
        "title": "How to work with Yandex Serverless Containers | Yandex Cloud documentation"
      },
      {
        "used": true,
        "url": "https://yandex.cloud/ru/docs/serverless-containers/concepts/container",
        "title": "Container in Yandex Serverless Containers | Yandex Cloud documentation"
      },
      {
        "used": true,
        "url": "https://yandex.cloud/ru/docs/container-registry/operations/docker-image/docker-image-push",
        "title": "Pushing a Docker image to a registry in Container Registry | Yandex Cloud documentation"
      },
      {
        "used": false,
        "url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/deploy-app-container",
        "title": "Running a containerized app in Yandex Serverless Containers | Yandex Cloud documentation"
      },
      {
        "used": false,
        "url": "https://yandex.cloud/ru/docs/container-registry/tutorials/fault-tolerance",
        "title": "Configuring a fault-tolerant architecture in Yandex Cloud | Yandex Cloud documentation"
      },
      {
        "used": false,
        "url": "https://yandex.cloud/ru/docs/serverless-containers/tf-ref",
        "title": "Terraform reference for Yandex Serverless Containers | Yandex Cloud documentation"
      }
    ],
    "searchQueries": [
      {
        "text": "what is containerization and how is it implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
        "reqId": "1742492744075717-6834712924673670818-e23cqdex********-BAL"
      },
      {
        "text": "how containerization is implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
        "reqId": "1742492744352285-5531077099747983300-hhsihxn5********-BAL"
      },
      {
        "text": "what is containerization date 2025 01 01 date 2025 01 01 date 2025 01 01",
        "reqId": "1742492744351443-10540017330195862709-gai4ndrg********-BAL"
      }
    ],
    "isAnswerRejected": false,
    "isBulletAnswer": false,
    "fixedMisspellQuery": "What is containerization and how is it implemented in Yandex Cloud?"
  }
]
{
  "message": {
    "content": "<response_text>",
    "role": "ROLE_ASSISTANT"
  },
  "sources": [
    {
      "url": "<link_to_found_document_1>",
      "title": "<title_of_found_document_1>",
      "used": false|true
    },
    {
      "url": "<link_to_found_document_2>",
      "title": "<title_of_found_document_2>",
      "used": false|true
    },
    ...
    {
      "url": "<link_to_found_document_n>",
      "title": "<title_of_found_document_n>",
      "used": false|true
    }
  ],
  "search_queries": [
    {
      "text": "<query_1_text>",
      "req_id": "<query_1_ID>"
    },
    {
      "text": "<query_2_text>",
      "req_id": "<query_2_ID>"
    },
    ...
    {
      "text": "<query_n_text>",
      "req_id": "<query_n_ID>"
    },
  ],
  "is_answer_rejected": false|true,
  "is_bullet_answer": false|true,
  "fixed_misspell_query": "<fixed_query_text >"
}

Where:

  • message.content: Text of the generative response. The footnotes within the text refer to sources, the list and order of which are given in the sources field.

  • sources: Array of source documents that were found during the query, could be used by YandexGPT as data sources when forming the response, and can be footnoted in the message.content field. Each source document contains the following fields:

    • url: Document URL.
    • title: Document title.
    • used: Indicates whether the document was used to generate the response. The possible values are true or false.
  • search_queries: List of additional search queries sent by the generative model to the search engine. Each query contains the following fields:

    • text: Search query text.
    • req_id: Yandex Search API unique query ID.
  • is_answer_rejected: Indicates the model's refusal to provide a response for ethical reasons:

    • false: Model has returned a response.
    • true: Model has refused to return a response.
  • is_bullet_answer: Indicates a bullet response where the model cannot give a proper response and suggests a set of bullets with various information:

    • false: Model gave a good answer.
    • true: Model suggested a set of bullets.
  • fixed_misspell_query: Fixed query text. This parameter is optional. It appears in the response only if you provide fix_misspell in the request body and typos were found in the query text.

Here is an example of a generative response with website limitation:
{
  "message": {
    "content": "**Containerization** (OS-level virtualization) is a **virtualization method** 
    in which the OS kernel manages several isolated user-space instances 
    instead of a single one. [1] These instances (containers or zones) are identical 
    to a separate OS instance in terms of the processes running inside them. [1] vCPU provides 
    complete container isolation, so applications from different containers have no impact 
    on one another. [1]\n\n**In Yandex Cloud, containerization is implemented with the help of 
    Yandex Serverless Containers**. [7] It allows you to run an application 
    contained in a Docker image, in Yandex Cloud. [7] \n\n**Some aspects of containerization in 
    Yandex Cloud:**\n\n* **Creating a container revision**. [7] You can only create a revision 
    from a Docker image uploaded to a registry in Yandex Container Registry. [7] Other registries are not supported. 
    supported. [7] The revision contains all the information you need to run the container. [7]\n* **Invoking 
    a container**. [7] Once you have created a revision, you can invoke the container via HTTPS using a trigger 
    or the Yandex API Gateway extension. [7]\n* **Scaling a container**. [7] If the container is invoked 
    faster than the instance can process the request, the service scales the container by running 
    its additional instances. [7] This ensures parallel processing of queries. [7]\n* 
    **Provisioned instances**. [7] This is a container instance that is guaranteed not to have 
    a cold start when you run it. [7] In a provisioned instance, before the container is invoked, 
    the Serverless Containers runtime components are initialized, and the user application is loaded and initialized. [7]",
    "role": "ROLE_ASSISTANT"
  },
  "sources": [
    {
      "url": "https://ru.wikipedia.org/wiki/%D0%9A%D0%BE%D0%BD%D1%82%D0%B5%D0%B9%D0%BD%D0%B5%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F",
      "title": "Containerization (Wikipedia)",
      "used": false
    },
    {
      "url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/functions-framework-to-container",
      "title": "Developing functions in Functions Framework and deploying them to Yandex Serverless Containers | Yandex Cloud documentation",
      "used": true
    },
    {
      "url": "https://yandex.cloud/ru/docs/container-registry/",
      "title": "Yandex Container Registry | Yandex Cloud documentation",
      "used": false
    },
    {
      "url": "https://yandex.cloud/ru/docs/container-registry/concepts/docker-image",
      "title": "Docker image. What is it and how does it work? | Yandex Cloud documentation",
      "used": false
    },
    {
      "url": "https://yandex.cloud/ru/docs/container-registry/operations/docker-image/docker-image-push",
      "title": "Pushing a Docker image to a registry in Container Registry | Yandex Cloud documentation",
      "used": false
    },
    {
      "url": "https://yandex.cloud/ru/docs/serverless-containers/tutorials/deploy-app-container",
      "title": "Running a containerized app in Yandex Serverless Containers | Yandex Cloud documentation",
      "used": false
    },
    {
      "url": "https://yandex.cloud/ru/docs/serverless-containers/concepts/container",
      "title": "Container in Yandex Serverless Containers | Yandex Cloud documentation",
      "used": false
    },
    {
      "url": "https://yandex.cloud/ru/docs/serverless-containers/tf-ref",
      "title": "Terraform reference for Yandex Serverless Containers | Yandex Cloud documentation",
      "used": true
    },
    {
      "url": "https://yandex.cloud/ru/docs/serverless-containers/operations/",
      "title": "How to work with Yandex Serverless Containers | Yandex Cloud documentation",
      "used": false
    },
    {
      "url": "https://yandex.cloud/ru/docs/container-registry/tutorials/fault-tolerance",
      "title": "Configuring a fault-tolerant architecture in Yandex Cloud | Yandex Cloud documentation",
      "used": false
    }
  ],
  "search_queries": [
    {
      "text": "what is containerization and how is it implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
      "req_id": "1742493532407414-13584885235180537459-jjleoq7t********-BAL"
    },
    {
      "text": "how containerization is implemented in yandex cloud date 2025 01 01 date 2025 01 01 date 2025 01 01",
      "req_id": "1742493532717030-17218638161437229208-rs6g5w5h********-BAL"
    },
    {
      "text": "what is containerization date 2025 01 01 date 2025 01 01 date 2025 01 01",
      "req_id": "1742493532716328-3123354248981714225-rs6g5w5h********-BAL"
    }
  ],
  "is_answer_rejected": false,
  "is_bullet_answer": false,
  "fixed_misspell_query": "What is containerization and how is it implemented in Yandex Cloud?"
}

Response featuresResponse features

Based on the query and search results, Yandex Search API may include the following warnings in a generative response:

  • If no relevant documents were found:

    No results found.
    Rephrase your query or ask something else.

  • If Yandex Search API has found the relevant source documents but was unable to extract information:

    Failed to extract the requested information from the documents. You can try opening them yourself or view the search results.

  • If Yandex Search API has found the source documents and succeeded extracting the information but is doubtful about response quality, it will preface its response with:

    There is various information on this topic online. You can find its overview below.

Was the article helpful?

Previous
HTML response
Next
Image search
© 2025 Direct Cursus Technology L.L.C.