GetEventsLog (Live)

Returns entries from the events log.

Yandex.Direct automatically registers events related to shared accounts, campaigns and ads, such as moderation results, new credits to the account balance, and others. The events log is separate for each user. The GetEventsLog method returns entries from the events log for the specified period of time.

New in the Live 4 version

The Currency input parameter is required.

Added the Currency input parameter and the Currency output parameter.

Added the AccountIDS input parameter and the AccountID output parameter.

Added the Limit and Offset input parameters.

Input data

The input data structure in JSON is shown below.

{
   "method": "GetEventsLog",
   "param": {
      /* GetEventsLogRequest */
      "TimestampFrom": (string),
      "TimestampTo": (string),
      "LastEventOnly": (string),
      "WithTextDescription": (string),
      "Currency": (string),
      "Logins": [
         (string)
         ...
      ],
      "Filter": {
         /* GetEventsLogFilter */
         "CampaignIDS": [
            (int)
            ...
         ],
         "BannerIDS": [
            (long)
            ...
         ],
         "PhraseIDS": [
            (long)
            ...
         ],
         "AccountIDS": [
            (int)
            ...
         ],
         "EventType": [
            (string)
            ...
         ]
      },
      "Limit": (int),
      "Offset": (int)
   }
}

Parameters are described below.

Parameter Description Required
GetEventsLogRequest object
TimestampFrom

The time at which to start recording events. Specified in ISO 8601 format, for example: 2011-05-24T23:59:59Z.

Yes
TimestampTo

The time at which to stop recording events. Specified in ISO 8601 format, for example: 2011-05-25T23:59:59Z.

If the parameter is omitted, all entries are returned up to the current time.

No
LastEventOnly

Get only the last entry for each type of event — Yes/No.

If omitted, returns all entries for the specified time period.

No
WithTextDescription

Output event descriptions to the response — Yes/No.

If the parameter is omitted, descriptions are not output.

No
Currency

The currency to use for monetary values (minimum price, remaining funds, amount credited) in the response.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

Yes
Logins

Array of usernames belonging to advertising agency clients. The method returns entries of events for the specified clients.

If omitted, it returns entries of events for the user who made the request.

Advertising agencies only
Filter The GetEventsLogFilter object with filtering conditions for event entries. If omitted, filtering is not applied, and the method returns all entries for the specified time period. No
Limit

The number of events to return (page size). You can combine this with the Offset parameter to set up paginated selections. The list of events, sorted by time.

If omitted, all events are returned.

No
Offset The number of events to skip when getting the selection. It is ignored if Limit is not defined. No
GetEventsLogFilter object
CampaignIDS IDs of campaigns that you need to get event entries for. No
BannerIDS IDs of ads that you need to get event entries for. No
PhraseIDS IDs of keywords that you want to get event entries for. No
AccountIDS Identifiers of shared accounts that you need to get event entries for. No
EventType

Types of events to get entries for. Acceptable values are shown below:

  • BannerModerated — Ad was checked by a moderator.
  • CampaignFinished — Campaign was stopped because of reaching the date for finishing impressions.
  • LowCTR — Keyword was disabled due to a low CTR.
  • MoneyOut — The campaign or shared account balance is out of funds.
  • MoneyWarning — The campaign or shared account balance is down to the level that requires sending notification (see the MoneyWarningValue parameter).
  • MoneyIn — Campaign or shared account balance has been topped off.
  • PausedByDayBudget — Campaign has been stopped because the daily budget limit has been reached.
  • WarnMinPrice — The minimum CPC has changed.
  • WarnPlace —The ad's display position has changed.
No

Output data

The method returns an array of EventsLogItem objects, each of which represents a single event entry. The output data structure in JSON is shown below.

{
   "data": [
      {  /* EventsLogItem */
         "AccountID": (int),
         "CampaignID": (int),
         "BannerID": (long),
         "PhraseID": (long),
         "TextDescription": (string),
         "EventType": (string),
         "Timestamp": (string),
         "EventName": (string),
         "Attributes": {
            /* EventsLogItemAttributes */
            "ModerationResult": (string),
            "MinPrice": (float),
            "Rest": (float),
            "Payed": (float),
            "FinishDate": (date),
            "OldPlace": (string),
            "IsEditedByModerator": (string),
            "StopTime": (string),
            "Currency": (string)
         }
      }
      ...
   ]
}

Parameters are described below.

Parameter Description
EventsLogItem object
AccountID Identifier of the shared account that the event is related to. May be omitted.
CampaignID ID of the campaign that the event is associated with. May be omitted.
BannerID ID of the ad that the event is associated with. May be omitted.
PhraseID ID of the keyword that the event is associated with. May be omitted.
TextDescription Description of the event.
EventType

Type of event. One of these values:

  • BannerModerated — Ad was checked by a moderator.
  • CampaignFinished — Campaign was stopped because of reaching the date for finishing impressions.
  • LowCTR — Keyword was disabled due to a low CTR.
  • MoneyOut — The campaign or shared account balance is out of funds.
  • MoneyWarning — The campaign or shared account balance is down to the level that requires sending notification (see the MoneyWarningValue parameter).
  • MoneyIn — Campaign or shared account balance has been topped off.
  • PausedByDayBudget — Campaign has been stopped because the daily budget limit has been reached.
  • WarnMinPrice — The minimum CPC has changed.
  • WarnPlace —The ad's display position has changed.
Timestamp Time when the event was registered (ISO 8601 format), for example: 2011-05-25T23:59:59Z.
EventName Brief description of the event.
Attributes EventsLogItemAttributes object with event parameters. The set of parameters depends on EventType.
EventsLogItemAttributes object
ModerationResult Moderation results. Output for the BannerModerated event.
MinPrice

The actual minimum CPC. Output for the WarnMinPrice event.

The value is converted to the currency specified in the Currency parameter and rounded up to the nearest bid increment in this currency.

Rest

Remaining funds on the campaign balance. Output for the MoneyWarning event.

The value is converted to the currency specified in the Currency parameter and mathematically rounded to the second decimal point.

If the value is expressed in a real currency, it does not include VAT.

Payed

Amount of funds credited. Output for the MoneyIn event.

The value is converted to the currency specified in the Currency parameter and mathematically rounded to the second decimal point.

If the value is expressed in a real currency, it does not include VAT.

FinishDate Date when the campaign was stopped. Output for the CampaignFinished event.
OldPlace Previous display position of the ad. Output for the WarnPlace event.
IsEditedByModerator Indicates whether the ad was changed by the moderator (Yes/No). Output for the BannerModerated event.
StopTime The date and time when the campaign was stopped. Output for the PausedByDayBudget event.
Currency

The currency that monetary values are shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN.

Examples of input data

Python

{
   'TimestampFrom': '2012-02-15T23:59:59Z',
   'TimestampTo': '2012-02-18T23:59:59Z',
   'Filter': {
      'CampaignIDS': [3193279],
      'EventType': ['MoneyIn', 'CampaignFinished']
   }
}

PHP

array(
   'TimestampFrom' => '2012-02-15T23:59:59Z',
   'TimestampTo' => '2012-02-18T23:59:59Z',
   'Filter' => array(
      'CampaignIDS' => array(3193279),
      'EventType' => array('MoneyIn', 'CampaignFinished')
   )
)

Perl

{
   'TimestampFrom' => '2012-02-15T23:59:59Z',
   'TimestampTo' => '2012-02-18T23:59:59Z',
   'Filter' => {
      'CampaignIDS' => [3193279],
      'EventType' => ['MoneyIn', 'CampaignFinished']
   }
}