# Яндекс Вордстат

Collect the semantics for a new landing page in chat

Статистика поисковых запросов — топ фраз, динамика, распределение по регионам

## How the agent works with Яндекс Вордстат

The agent calls the wordstat section of the Yandex Cloud Search API: it sends a phrase and gets back the top queries containing that word, related wordings for the last 30 days, dynamics by day, week and month, and a frequency breakdown by region and device. It pulls the region reference list with a separate request so that filters and city names in the report match the service's own directory instead of being guessed.

Wordstat counts impressions in search, not people and not future traffic — and the agent labels the number exactly that way. The frequency of a broad phrase absorbs all of its refinements, so the figure for a word is always larger than the sum of the specific queries, and switching the region rewrites the whole picture. With every number the agent states the period and the region it came from, so that comparing naming options runs on the same basis.

There is nothing to write here and the agent does not pretend otherwise: it creates and changes nothing in Yandex Cloud, and the key is used only for statistics requests. The work is entirely analytical — collecting the semantics for a new page, seeing the peaks and dips of demand before they reach revenue, finding the regions where demand runs ahead of your presence, and comparing several wordings of a service before launch.

The key travels as an authorization header on every request and is stored encrypted; revoking it in the cloud kills the connection at once, and the scope never reaches past statistics into the rest of the cloud anyway. Calls are deliberately spaced out — on average around one request every half a minute — so a long list of phrases fills in gradually and billing goes by actual usage. An empty result for a phrase is named as such, not passed off as absent demand.

## Integration scenarios

### Semantics for a new landing page
The agent collects the top phrases containing your keyword plus related queries for the last 30 days and shows the wording people actually search for.

### Seasonality of demand
The agent charts query dynamics by day, week or month and surfaces the peaks and dips before they show up in revenue.

### Demand by region
The agent breaks phrase frequency down by region and city and shows where demand runs ahead of your current presence.

### Testing the wording before launch
The agent compares the frequency of several names or service wordings and shows which one people search for and which one barely appears at all.

### Demand coming from phones
The agent breaks phrase frequency down by device and shows what share of demand comes from phones and what from desktop, over the same period and region.

### A long list of phrases
The agent works through a list of hundreds of phrases gradually, roughly one request every half a minute, and returns a finished table without hitting the service limit.

## How to connect

**Before you connect**

- A Yandex Cloud account with admin rights on the folder.
- A cloud linked to a billing account: Search API is paid.

### Create a service account in Yandex Cloud
Yandex Cloud console → “Identity and Access Management” → “Service accounts” → “Create service account”. The cloud must be linked to a billing account.

### Grant the search-api.webSearch.user role
On the folder, assign the service account the search-api.webSearch.user role. Do not use the deprecated search-api.executor.

### On the account page create an API key
On the account page: “Create new key” → “Create API key”, pick yc.search-api.execute in the “Scope” field. The key starts with AQVN and is shown once.

### Copy the folder ID under the folder name
In the console open the folder you need — its ID is shown under the name and copies on click. It is a roughly 20-character string starting with b1.

## FAQ

### How do I connect Yandex Wordstat?
With two values from Yandex Cloud: a service account API key starting with AQVN and the catalog Folder ID. The account needs the search-api.webSearch.user role, and the key is created with the yc.search-api.execute scope.

### What does the agent get from Wordstat?
Search phrase frequency and related queries, dynamics by day, week and month, breakdowns by region and device, and the region reference list for filters.

### Does the agent write anything to the service?
No, this is reference statistics: the agent sends a phrase and gets demand figures back. It cannot create or change anything in Yandex Cloud, the key is used only for Search API requests.

### Why does a long list of phrases take so long?
Search API calls are deliberately spaced out in time, so a batch of phrases fills in gradually. Requests are billed as used, and the cloud must be linked to a billing account.

[Open Яндекс Вордстат](https://console.yandex.cloud)