Contact UsGet started

Generative response

Written by
Updated at April 21, 2025

You can use Yandex Search API text search together with YandexGPT generative AI to get a comprehensive and concise generative response to a user query. To generate such a response, the model analyzes the relevant text search results retrieved by Yandex Search API from your company's websites.

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.

The generative response feature is only available in the API v2 interface. For more information on the pricing of generative responses to queries, see Yandex Search API pricing policy.

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

Note

You can get a generative response only when searching within a given search area: an array of sites, hosts, or pages. No generative response is available when querying the Yandex search database.

Request body format

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

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

{
  "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_n_address_for_search>"
    ]
  },
  "host": {
    "host": [
      "<host_1_for_search>",
      "<host_2_for_search>",
      ...
      "<host_n_for_search>"
    ]
  },
  "url": {
    "url": [
      "<page_1_for_search>",
      "<page_2_for_search>",
      ...
      "<page_n_for_search>"
    ]
  },
  "folderId": "<folder_ID>",
  "fixMisspell": true|false,
  "enableNrfmDocs": true|false,
  "searchFilters": [
    {
      "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 YandexGPT Lite or YandexGPT Pro.

  • Use the site, host, and url fields to set the search scope. This is a required parameter in a query. Note that the site, host, and url fields are mutually exclusive; you can only set one of them.

    • site: Restricts the search to a specific array of websites.

      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.

      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.

  • 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": ">2025-01-01", 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.
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": ">2025-01-01"
    }
  ]
}

{
  "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_n_address_for_search>"
    ]
  },
  "host": {
    "host": [
      "<host_1_for_search>",
      "<host_2_for_search>",
      ...
      "<host_n_for_search>"
    ]
  },
  "url": {
    "url": [
      "<page_1_for_search>",
      "<page_2_for_search>",
      ...
      "<page_n_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 YandexGPT Lite or YandexGPT Pro.

  • Use the site, host, and url fields to set the search scope. This is a required parameter in a query. Note that the site, host, and url fields are mutually exclusive; you can only set one of them.

    • site: Restricts the search to a specific array of websites.

      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.

      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.

  • 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": ">2025-01-01", 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.
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/"
    ]
  },
  "folder_id": "aoevhr118rhc********",
  "fix_misspell": "true",
  "enable_nrfm_docs": "true",
  "search_filters": [
    {
      "date": ">2025-01-01"
    }
  ]
}

Submitting a query

To send a query, 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.

Generative response

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

{
  "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.

  • 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 core supports multiple 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] The core provides complete container isolation, so programs 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] It allows you to run in Yandex Cloud the application contained in a Docker image. [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 Yandex API Gateway extension.
      [6]\n* **Scaling a container**. [6] If the container is invoked faster than the instance can process the query, the service scales the container by running additional instances of it.
      [6] This ensures parallel processing of queries.
      [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": "Guides on using 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 core supports multiple 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] The core provides complete container isolation, so programs 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 in Yandex Cloud the application contained in a Docker image.
    [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.
    [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 Yandex API Gateway extension.
    [7]\n* **Scaling a container**. [7] If the container is invoked faster than the instance can process the query, the service scales the container by running additional instances of it.
    [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": "Guides on using 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 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.

Previous
HTML response
Next
Quotas and limits