Usage limitations

Access restrictions

Clients of advertising agencies can get API access:
  • 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.

Technical limitations

  1. A maximum of five simultaneous API requests are allowed from a single user.

  2. 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.
  3. For the following methods, a limit is imposed on the amount of input data:

  4. Using the CreateNewSubclient method, an advertising agency can register no more than 100 clients per day.

  5. Financial transactions have the following restrictions:

  6. For the following methods, a restriction is applied to the number of reports that can be stored on the server simultaneously:

Point limitations

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:

  1. CreateOrUpdateBanners:

    • Creating an ad ― 12 points.
    • Editing an ad ― 4 points.
    • Adding a keyword ― 2 points.
    • Editing a keyword ― 1 point.
  2. GetKeywordsSuggestion — 3 points per keyword.

  3. CreateNewWordstatReport — 10 points per keyword.

  4. AdImage (Live) — 2 points per image loaded.
  5. AdImageAssociation (Live):
    • Adding an association between an image and an ad — 2 points.

    • Removing an association — 1 point.

    Note. When adding/removing an association between an image and an ad that has the “Draft” status, points are not deducted.

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.

Restriction on getting auction results

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.

Example

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 GetBanners or GetBanners (Live) method if WithPrices is specified in the GetPhrases input parameter.

  • 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.

  • Calling the GetBannerPhrases or GetBannerPhrases (Live). finance method.

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.

Example:
GetPhrasesLimit: 1/23553853/23553900/1922 secs