Restrictions when working with the Yandex.Direct API
The Yandex.Direct API is provided free of charge, but the number and type of operations you can perform depend on certain restrictions.
There are several types of restrictions in the API:
- If the agency granted the client read-only access to the web interface, the client can only get data when using the API, as well.
- If the agency granted the client permission to edit campaigns, the client can use either the web interface or the API for managing campaigns.
An agency sets up access permissions for its clients using the UpdateClientInfo method, and also in the web interface (the edit campaign option on the page for editing client settings).
API access may be restricted by IP address, for increased information security. You can specify the list of allowed IP addresses on the Direct API access management page on the Settings tab.
A maximum of five simultaneous API requests are allowed from a single user.
For the following methods, a limit is imposed on the number of calls per day (24-hour period).
Important. If you have reached the maximum, the method will be available only once every 10 minutes until the start of the next day.
- CreateOrUpdateCampaign ― 100 calls for editing each campaign and 100 calls for creating campaigns.
- CreateOrUpdateBanners -1000 calls to the campaign.
- SetAutoPrice ― 100 calls per campaign.
- UpdatePrices ― 3000 calls to the campaign. You can set prices for a maximum of 1000 keywords in a single request.
- CreateNewReport and GetBannersStat― 300 calls per campaign.
- GetSummaryStat ― 100 calls to the campaign.
- GetKeywordsSuggestion ― 3000 calls from a single user.
- CreateInvoice, GetCreditLimits, PayCampaigns, TransferMoney - 1000 calls on behalf of one user.
- All other methods ― 50,000 calls on behalf of a single user.
For the following methods, a limit is imposed on the amount of input data:
- CreateOrUpdateBanners - up to 1000 ads.
- UpdatePrices - Up to 1000 phrases.
- GetSummaryStat ― the number of requested campaigns multiplied by the number of days in the selected period must not exceed 1000.
- CreateNewForecast ― up to 100 keywords.
- CreateNewWordstatReport ― up to 10 keywords per request, and up to 1000 keywords per day.
- GetBanners ― up to 2000 ads or up to 10 campaigns in a single request.
- GetBannerPhrases, GetBannerPhrasesFilter ― up to 1000 ads per request.
- GetClientInfo — up to 1000 usernames.
- StopBanners, ResumeBanners, ArchiveBanners, UnArchiveBanners, DeleteBanners — up to 2000 ad IDs.
Using the CreateNewSubclient method, an advertising agency can register no more than 100 clients per day.
Financial transactions have the following restrictions:
- Up to 30 financial transactions per day per campaign, including calls of the CreateInvoice and PayCampaigns methods and transferring funds using the TransferMoney method (deducting funds using the TransferMoney method does not count).
- Up to 30 financial transactions per day per shared account, as the total of the Deposit and Invoice operations for the AccountManagement (Live) method.
- Up to 3 TransferMoney operations for the AccountManagement (Live) method per day per shared account (both credits and deposits are counted).
- For the following methods, a restriction is applied to the number of reports that can be stored on the server simultaneously:
Once per day, points are awarded to each API user. They do not accumulate, and are awarded starting from zero each day. Points are used as a method of paying for certain API operations (see below). If you do not have enough points, you cannot perform these operations. The GetClientsUnits method returns the number of points available to the user.
Points are used when calling the following methods:
- Creating an ad ― 12 points.
- Editing an ad ― 4 points.
- Adding a keyword ― 2 points.
- Editing a keyword ― 1 point.
GetKeywordsSuggestion — 3 points per keyword.
CreateNewWordstatReport — 10 points per keyword.
- AdImage (Live) — 2 points per image loaded.
- AdImageAssociation (Live):
Note. When adding/removing an association between an image and an ad that has the “Draft” status, points are not deducted.
Adding an association between an image and an ad — 2 points.
Removing an association — 1 point.
The more efficiently you use Yandex.Direct, the more points you will be awarded. Inefficient use is generally associated with creating ads that are rejected during moderation or adding keywords that have a low CTR. These sorts of practices waste the resources of Yandex.Direct and are not encouraged.
Efficient use of Yandex.Direct is associated with searching for successful keywords and ad texts that raise the CTR. The number of points also depends on the campaign size and advertising expenditures. This means that more points are awarded to users who have a higher campaign balance and higher bids.
Each advertiser is given an individual daily limit on auction calls — a restriction on the number of keywords that you can get auction results for. This limit depends on the activity of advertising campaigns — the number of impressions and clicks, and resulting expenditures.
If the number of impressions and clicks isn't growing much or the campaign is short of funds, frequent requests for auction results is an unreasonable load on the Yandex.Direct servers. The daily limit is calculated using a grid of budget thresholds based on statistics for different types of campaigns.
The daily limit is divided among 24 hour-long periods and provided on a sliding window principle. In the current hour-long period, the advertiser may spend the daily limit minus the number of keywords that auction results were requested for over the previous 23 periods.
The start time of the hourly period may differ for different advertisers and might not coincide with the beginning of the astronomical hour.
Let's assume the daily limit on bid requests for an advertiser is 1.5 million keywords, and the time periods begin at 00:18, 01:18, 02:18, and so on.
If the advertiser got auction results for 1.4 million keywords between 12:18 of the previous day and 11:18 of the current day, the advertiser can get auction results for 100,000 keywords from 11:18 to 12:18. At 12:18, the remainder of the limit is recalculated.
Getting auction results includes the following API requests:
Calling the GetBannerPhrasesFilter method if the RequestPrices parameter is omitted or set to "No".
Calling the GetBannerPhrasesFilter (Live) method if the FieldNames parameter isn't set, or if the array has at least one of the values Prices, Max, Min, PremiumMax, PremiumMin, LowCTR, ContextLowCTR, Shows, Clicks, ContextShows, ContextClicks, CurrentOnSearch, LowCTRWarning, MinPrice, ContextCoverage, Coverage, AuctionBids.
In these cases, the method response contains the
GetPhrasesLimit HTTP header, which specifies:
The number of keywords that auction results were received for when calling the method.
The available remainder of the daily limit.
The daily limit.
The number of seconds until the start of the next hourly period.
GetPhrasesLimit: 1/23553853/23553900/1922 secs
If you have more questions, contact us using the form below. Please explain your question and the situation in as much detail as possible so that we can give you a comprehensive answer.
For questions related to restrictions on specific Yandex.Direct API methods, you must provide the following information:
- The username of the user making requests to the Yandex.Direct API.
- The complete JSON or XML code of the request to the API server.
- The complete JSON or XML code of the response from the API server.
- The exact time of the request (MSK).