GetCampaignsListFilter
Returns a list of campaigns that meet the filter conditions with brief information about these campaigns.
Disabled method. Use version 5 of the API.
For information about the compatibility of methods between versions 4 and 5, see the Migration guide.
The GetCampaignsListFilter (Live) version also exists for this method.
Restrictions
Input data
The input data structure in JSON is shown below.
{
"method": "GetCampaignsListFilter",
"param": {
/* GetCampaignsInfo */
"Logins": [
(string)
...
],
"Filter": {
/* CampaignsFilterInfo */
"StatusModerate": [
(string)
...
],
"IsActive": [
(string)
...
],
"StatusArchive": [
(string)
...
],
"StatusActivating": [
(string)
...
],
"StatusShow": [
(string)
...
]
}
}
}
Parameters are described below.
Parameter | Description | Required |
GetCampaignsInfo object | ||
---|---|---|
Logins | An array containing the usernames of clients (100 maximum) that you need to get a list of campaigns for. Only used for advertising agencies. Other users can omit this parameter. | Yes, for advertising agencies |
Filter | The CampaignsFilterInfo object, which contains the conditions for filtering campaigns. If omitted, brief information about all campaigns is returned, like in the method GetCampaignsList. | No |
CampaignsFilterInfo object | ||
StatusModerate | Filter campaigns based on moderation status:
| No |
IsActive | Filter campaigns based on active status:
"Active" is defined as the campaign state in which ad impressions are turned on and off automatically, according to the time targeting settings or depending on the campaign balance. An "inactive" campaign means that ad impressions are disabled by the client or Yandex manager and can't be enabled automatically. | No |
StatusArchive | Filter campaigns based on whether they are archived:
| No |
StatusActivating | Filter campaigns based on activation status:
| No |
StatusShow | Filter campaigns based on ad display:
| No |
Parameter | Description | Required |
GetCampaignsInfo object | ||
---|---|---|
Logins | An array containing the usernames of clients (100 maximum) that you need to get a list of campaigns for. Only used for advertising agencies. Other users can omit this parameter. | Yes, for advertising agencies |
Filter | The CampaignsFilterInfo object, which contains the conditions for filtering campaigns. If omitted, brief information about all campaigns is returned, like in the method GetCampaignsList. | No |
CampaignsFilterInfo object | ||
StatusModerate | Filter campaigns based on moderation status:
| No |
IsActive | Filter campaigns based on active status:
"Active" is defined as the campaign state in which ad impressions are turned on and off automatically, according to the time targeting settings or depending on the campaign balance. An "inactive" campaign means that ad impressions are disabled by the client or Yandex manager and can't be enabled automatically. | No |
StatusArchive | Filter campaigns based on whether they are archived:
| No |
StatusActivating | Filter campaigns based on activation status:
| No |
StatusShow | Filter campaigns based on ad display:
| No |
Output data
The method returns an array of ShortCampaignInfo objects containing campaign summaries. The output data structure in JSON is shown below.
{
"data": [
{ /* ShortCampaignInfo */
"CampaignID": (int),
"Login": (string),
"Name": (string),
"StartDate": (date),
"Sum": (float),
"Rest": (float),
"SumAvailableForTransfer": (float),
"Shows": (int),
"Clicks": (int),
"Status": (string),
"StatusShow": (string),
"StatusArchive": (string),
"StatusActivating": (string),
"StatusModerate": (string),
"IsActive": (string),
"ManagerName": (string),
"AgencyName": (string)
}
...
]
}
Parameters are described below.
Parameter | Description |
ShortCampaignInfo object | |
---|---|
CampaignID | The campaign ID. To create a campaign, it is set to 0; to change the parameters of an existing campaign, the campaign ID is specified. |
Login | Login name of the campaign owner (username of the Yandex user that the ad campaign is run for). When creating a campaign, direct advertisers set their own Yandex username, while advertising agencies set their client's username. When getting campaign parameters, the username of the advertiser's chief representative is returned. |
Name | The campaign name. |
StartDate | Date to start impressions, The date can be in the future. In this case, impressions begin on the specified date, if the moderator approved the ad and funds were transferred to the campaign balance. |
Sum | If the advertiser has the shared account enabled, this is the total amount of funds spent over the campaign's existence. If the shared account is disabled, this is the amount of funds added to the campaign over the campaign's existence. |
Rest | The current balance of the shared account + the amount refunded to the campaign (if the advertiser has the shared account enabled) or the current campaign balance (if the shared account is disabled). Note. The amount of money returned for clicks that the system determines to be fraudulent or mistaken; this amount can be spent only within the same campaign. |
SumAvailableForTransfer | The amount available to transfer using the TransferMoney method. It may be less than the campaign balance. It is returned only if the advertiser has not enabled the shared account. |
Shows | The number of impressions since the campaign was launched. |
Clicks | The number of clicks since the campaign was launched. |
Status | The campaign status. For example: “Running impressions”, “Waiting for payment”, “Under moderation”, “Stopped”, “Running impressions. Activating”, “Archived campaign”, and others. |
StatusShow | Ad impressions are enabled for the campaign — Yes/No. Turning on and off is performed by methods StopCampaign and ResumeCampaign. Allowing displays at the campaign level does not mean that the ad is actually displayed. For impressions, other conditions must be met as well: sufficient funds, moderator approval of the campaign and ads, and enabled displays on the ad level (ResumeBanners method). An actual impression corresponds to the Yes value in the IsActive parameter. |
StatusArchive | Campaign archive status:
Use the ArchiveCampaign method to transfer a campaign to the archive. Use the UnArchiveCampaign method to restore a campaign from the archive. |
StatusActivating | Campaign activation status:
|
StatusModerate | Moderation result:
Use the ModerateBanners method to submit a Creative for moderation. |
IsActive | The campaign is active and ads are being displayed — Yes/No. "Active" is defined as the campaign state in which ad impressions are turned on and off automatically, according to the time targeting settings or depending on the campaign balance. An "inactive" campaign means that ad impressions are disabled and can't be enabled automatically. |
ManagerName | Name of the personal Yandex manager. It is filled in automatically for campaigns that have a personal manager. |
AgencyName | Name of the advertising agency. It is filled in automatically if the campaign was created by an agency. |
Parameter | Description |
ShortCampaignInfo object | |
---|---|
CampaignID | The campaign ID. To create a campaign, it is set to 0; to change the parameters of an existing campaign, the campaign ID is specified. |
Login | Login name of the campaign owner (username of the Yandex user that the ad campaign is run for). When creating a campaign, direct advertisers set their own Yandex username, while advertising agencies set their client's username. When getting campaign parameters, the username of the advertiser's chief representative is returned. |
Name | The campaign name. |
StartDate | Date to start impressions, The date can be in the future. In this case, impressions begin on the specified date, if the moderator approved the ad and funds were transferred to the campaign balance. |
Sum | If the advertiser has the shared account enabled, this is the total amount of funds spent over the campaign's existence. If the shared account is disabled, this is the amount of funds added to the campaign over the campaign's existence. |
Rest | The current balance of the shared account + the amount refunded to the campaign (if the advertiser has the shared account enabled) or the current campaign balance (if the shared account is disabled). Note. The amount of money returned for clicks that the system determines to be fraudulent or mistaken; this amount can be spent only within the same campaign. |
SumAvailableForTransfer | The amount available to transfer using the TransferMoney method. It may be less than the campaign balance. It is returned only if the advertiser has not enabled the shared account. |
Shows | The number of impressions since the campaign was launched. |
Clicks | The number of clicks since the campaign was launched. |
Status | The campaign status. For example: “Running impressions”, “Waiting for payment”, “Under moderation”, “Stopped”, “Running impressions. Activating”, “Archived campaign”, and others. |
StatusShow | Ad impressions are enabled for the campaign — Yes/No. Turning on and off is performed by methods StopCampaign and ResumeCampaign. Allowing displays at the campaign level does not mean that the ad is actually displayed. For impressions, other conditions must be met as well: sufficient funds, moderator approval of the campaign and ads, and enabled displays on the ad level (ResumeBanners method). An actual impression corresponds to the Yes value in the IsActive parameter. |
StatusArchive | Campaign archive status:
Use the ArchiveCampaign method to transfer a campaign to the archive. Use the UnArchiveCampaign method to restore a campaign from the archive. |
StatusActivating | Campaign activation status:
|
StatusModerate | Moderation result:
Use the ModerateBanners method to submit a Creative for moderation. |
IsActive | The campaign is active and ads are being displayed — Yes/No. "Active" is defined as the campaign state in which ad impressions are turned on and off automatically, according to the time targeting settings or depending on the campaign balance. An "inactive" campaign means that ad impressions are disabled and can't be enabled automatically. |
ManagerName | Name of the personal Yandex manager. It is filled in automatically for campaigns that have a personal manager. |
AgencyName | Name of the advertising agency. It is filled in automatically if the campaign was created by an agency. |
Examples of input data
Python
{
'Logins': ['agrom'],
'Filter': {
'IsActive': ['Yes'],
'StatusShow': ['Yes']
}
}
PHP
array(
'Logins' => array('agrom'),
'Filter' => array(
'IsActive' => array('Yes'),
'StatusShow' => array('Yes')
)
)
Perl
{
'Logins' => ['agrom'],
'Filter' => {
'IsActive' => ['Yes'],
'StatusShow' => ['Yes']
}
}