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.

ParameterDescriptionRequired
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
FilterThe 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
OffsetThe number of events to skip when getting the selection. It is ignored if Limit is not defined.No
GetEventsLogFilter object
CampaignIDSIDs of campaigns that you need to get event entries for.No
BannerIDSIDs of ads that you need to get event entries for.No
PhraseIDSIDs of keywords that you want to get event entries for.No
AccountIDSIdentifiers 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.

ParameterDescription
EventsLogItem object
AccountIDIdentifier of the shared account that the event is related to. May be omitted.
CampaignIDID of the campaign that the event is associated with. May be omitted.
BannerIDID of the ad that the event is associated with. May be omitted.
PhraseIDID of the keyword that the event is associated with. May be omitted.
TextDescriptionDescription 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.
TimestampTime when the event was registered (ISO 8601 format), for example: 2011-05-25T23:59:59Z.
EventNameBrief description of the event.
AttributesEventsLogItemAttributes object with event parameters. The set of parameters depends on EventType.
EventsLogItemAttributes object
ModerationResultModeration 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.

FinishDateDate when the campaign was stopped. Output for the CampaignFinished event.
OldPlacePrevious display position of the ad. Output for the WarnPlace event.
IsEditedByModeratorIndicates whether the ad was changed by the moderator (Yes/No). Output for the BannerModerated event.
StopTimeThe 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']
   }
}