GetCampaignsList (Live)

Returns a list of campaigns with brief information about them.

Attention.

Disabled method. Use version 5 of the API.

For information about the compatibility of methods between versions Live 4 and 5, see the Migration guide.

Restrictions

Attention. This method only returns campaigns with the “Text & Image Ads” type. To work with all types of campaigns, use the Campaigns service in version 5 of the API. More information about campaign types

New in the Live 4 version

Added output parameters StrategyName and ContextStrategyName.

Added the output parameters CampaignCurrencyandSourceCampaignID (also see the section Real currencies instead of Yandex units).

Added the DayBudgetEnabled output parameter.

Added the EnableRelatedKeywords output parameter.

Added the ExtendedAdTitleEnabled output parameter.

Input data

The input data structure in JSON is shown below.

{
   "method": "GetCampaignsList",
   "param": [
      (string)
      ...
   ]
}

The param parameter is used only when making the request on behalf of an advertising agency. Use this parameter to specify an array of usernames (no more than 100) that you need to get a list of campaigns for. In all other cases, param can be omitted, and the method will return a list of campaigns for the user who made the request.

Output data

The output data structure in JSON is shown below.

{
   "data": [
      {  /* ShortCampaignInfo */
         "CampaignID": (int),
         "Login": (string),
         "Name": (string),
         "StartDate": (date),
         "StrategyName": (string),
         "ContextStrategyName": (string),
         "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),
         "CampaignCurrency": (string),
         "SourceCampaignID": (int),
         "DayBudgetEnabled": (string),
         "EnableRelatedKeywords": (string),
         "ExtendedAdTitleEnabled": (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.

StrategyName

Strategy on search. Acceptable values are listed below.

  • ShowsDisabled — Disable impressions on search. This is required when using an automatic strategy in the Yandex Advertising Network. Showing ads in the search cannot be disabled if the Default strategy is applied to the Yandex Advertising Network.

Strategies with manual bid management on search:

  • HighestPosition — “Highest available position” strategy.
  • LowestCost — “Cheapest position in ad block” strategy.
  • LowestCostPremium — “Cheapest position in ad block” strategy, but ads are displayed only in Premium Placement.
  • LowestCostGuarantee — “Impressions below search results” strategy (in the lower block at lowest cost).
  • RightBlockHighest — The “Impressions below search results” strategy (in the lower block at the highest position available for the specified bid).

Automatic strategies on search:

  • WeeklyBudget — The “Weekly budget: maximum clicks” strategy (mandatory parameter WeeklySumLimit; optional parameter MaxPrice).
  • CPAOptimizer — The “Weekly budget: maximum conversion rate” strategy (mandatory parameters WeeklySumLimit and GoalID; optional parameter MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • AverageClickPrice — The “Average CPC” strategy (mandatory parameter: AveragePrice; optional parameter: WeeklySumLimit).
  • WeeklyPacketOfClicks — The “Weekly click package” strategy (mandatory parameter: ClicksPerWeek; optional parameters: MaxPrice or AveragePrice).
  • AverageCPAOptimization — The “Average CPA” strategy (mandatory parameters AverageCPA and GoalID; optional parameters WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • ROIOptimization — The “Average ROI” strategy (mandatory parameters ReserveReturn, ROICoef, GoalID; optional parameters Profitability, WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
ContextStrategyName

Strategy in the Yandex Advertising Network. Acceptable values are listed below.

  • ShowsDisabled — Disable impressions in the Yandex Advertising Network. This is possible only if impressions are not disabled on search.

Strategies with manual bid management for the Yandex Advertising Network:

  • Default — The “Percentage of the price on Search” strategy. The percent is set in the ContextPricePercent parameter. There are additional optional parameters, ContextLimit and ContextLimitSum. This strategy is applied to campaigns that do not have a strategy explicitly set for them.

  • MaximumCoverage — “Maximum audience coverage” strategy. Bids are set using one of these methods: CreateOrUpdateBanners, SetAutoPrice (Live), UpdatePrices.

    Important. The MaximumCoverage strategy is not available if an automatic strategy is selected for search.

Automatic strategies in the Yandex Advertising Network:

Important.

Automatic strategies in the Yandex Advertising Network are available only if impressions are turned off for the search (ShowsDisabled strategy).

  • WeeklyBudget — The “Weekly budget: maximum clicks” strategy (mandatory parameter WeeklySumLimit; optional parameter MaxPrice).
  • CPAOptimizer — The “Weekly budget: maximum conversion rate” strategy (mandatory parameters WeeklySumLimit and GoalID; optional parameter MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • AverageClickPrice — The “Average CPC” strategy (mandatory parameter: AveragePrice; optional parameter: WeeklySumLimit).
  • WeeklyPacketOfClicks — The “Weekly click package” strategy (mandatory parameter: ClicksPerWeek; optional parameters: MaxPrice or AveragePrice).
  • AverageCPAOptimization — The “Average CPA” strategy (mandatory parameters AverageCPA and GoalID; optional parameters WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • ROIOptimization — The “Average ROI” strategy (mandatory parameters ReserveReturn, ROICoef, GoalID; optional parameters Profitability, WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
StartDate

Date to start impressions, YYYY-MM-DD. If omitted, the campaign creation date is used.

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

The value is in Yandex units.

If the campaign operates in a real currency, the returned value is converted from the campaign's currency to units and mathematically rounded to the second decimal place (see the section Real currencies instead of Yandex units).

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.

The value is in Yandex units.

If the campaign operates in a real currency, the returned value is converted from the campaign's currency to units and mathematically rounded to the second decimal place (see the section Real currencies instead of Yandex units).

SumAvailableForTransfer

The amount available to transfer using the TransferMoney method. It is returned only if the shared account is not enabled. It may be less than the campaign balance.

The value is in Yandex units.

If the campaign operates in a real currency, the returned value is converted from the campaign's currency to units and mathematically rounded to the second decimal place (see the section Real currencies instead of Yandex units).

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:

  • Yes — Campaign has been archived.
  • No — Campaign is not in the archive.
  • Pending — The campaign is being transferred to the archive, or is being restored from the archive.
  • CurrencyConverted — The campaign was automatically archived when switching the client to using currency, and cannot be unarchived (see the section Real currencies instead of Yandex units).

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:

  • Yes — Activated.
  • Pending — Waiting for activation.
StatusModerate

Moderation result:

  • Yes — Moderator approved at least one ad.
  • No — Moderator rejected all the ads.
  • New — Ads have not been submitted for moderation (the campaign has the “Draft” status).
  • Pending — Under moderation.

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.

CampaignCurrency

The currency the campaign operates in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. If the parameter is omitted or set to NULL, it means the campaign operates in Yandex units.

SourceCampaignID ID of the unit-based source campaign, if the current campaign was created automatically when switching the client to using currency (see the section Switching to currency). Otherwise, omitted or set to NULL.
DayBudgetEnabled Daily campaign budget management is available — Yes/No.
EnableRelatedKeywords

Related keywords tool enabled — Yes/No.

ExtendedAdTitleEnabled Substituting part of the ad text in the title is enabled — Yes/No.
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.

StrategyName

Strategy on search. Acceptable values are listed below.

  • ShowsDisabled — Disable impressions on search. This is required when using an automatic strategy in the Yandex Advertising Network. Showing ads in the search cannot be disabled if the Default strategy is applied to the Yandex Advertising Network.

Strategies with manual bid management on search:

  • HighestPosition — “Highest available position” strategy.
  • LowestCost — “Cheapest position in ad block” strategy.
  • LowestCostPremium — “Cheapest position in ad block” strategy, but ads are displayed only in Premium Placement.
  • LowestCostGuarantee — “Impressions below search results” strategy (in the lower block at lowest cost).
  • RightBlockHighest — The “Impressions below search results” strategy (in the lower block at the highest position available for the specified bid).

Automatic strategies on search:

  • WeeklyBudget — The “Weekly budget: maximum clicks” strategy (mandatory parameter WeeklySumLimit; optional parameter MaxPrice).
  • CPAOptimizer — The “Weekly budget: maximum conversion rate” strategy (mandatory parameters WeeklySumLimit and GoalID; optional parameter MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • AverageClickPrice — The “Average CPC” strategy (mandatory parameter: AveragePrice; optional parameter: WeeklySumLimit).
  • WeeklyPacketOfClicks — The “Weekly click package” strategy (mandatory parameter: ClicksPerWeek; optional parameters: MaxPrice or AveragePrice).
  • AverageCPAOptimization — The “Average CPA” strategy (mandatory parameters AverageCPA and GoalID; optional parameters WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • ROIOptimization — The “Average ROI” strategy (mandatory parameters ReserveReturn, ROICoef, GoalID; optional parameters Profitability, WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
ContextStrategyName

Strategy in the Yandex Advertising Network. Acceptable values are listed below.

  • ShowsDisabled — Disable impressions in the Yandex Advertising Network. This is possible only if impressions are not disabled on search.

Strategies with manual bid management for the Yandex Advertising Network:

  • Default — The “Percentage of the price on Search” strategy. The percent is set in the ContextPricePercent parameter. There are additional optional parameters, ContextLimit and ContextLimitSum. This strategy is applied to campaigns that do not have a strategy explicitly set for them.

  • MaximumCoverage — “Maximum audience coverage” strategy. Bids are set using one of these methods: CreateOrUpdateBanners, SetAutoPrice (Live), UpdatePrices.

    Important. The MaximumCoverage strategy is not available if an automatic strategy is selected for search.

Automatic strategies in the Yandex Advertising Network:

Important.

Automatic strategies in the Yandex Advertising Network are available only if impressions are turned off for the search (ShowsDisabled strategy).

  • WeeklyBudget — The “Weekly budget: maximum clicks” strategy (mandatory parameter WeeklySumLimit; optional parameter MaxPrice).
  • CPAOptimizer — The “Weekly budget: maximum conversion rate” strategy (mandatory parameters WeeklySumLimit and GoalID; optional parameter MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • AverageClickPrice — The “Average CPC” strategy (mandatory parameter: AveragePrice; optional parameter: WeeklySumLimit).
  • WeeklyPacketOfClicks — The “Weekly click package” strategy (mandatory parameter: ClicksPerWeek; optional parameters: MaxPrice or AveragePrice).
  • AverageCPAOptimization — The “Average CPA” strategy (mandatory parameters AverageCPA and GoalID; optional parameters WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
  • ROIOptimization — The “Average ROI” strategy (mandatory parameters ReserveReturn, ROICoef, GoalID; optional parameters Profitability, WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex Direct.
StartDate

Date to start impressions, YYYY-MM-DD. If omitted, the campaign creation date is used.

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

The value is in Yandex units.

If the campaign operates in a real currency, the returned value is converted from the campaign's currency to units and mathematically rounded to the second decimal place (see the section Real currencies instead of Yandex units).

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.

The value is in Yandex units.

If the campaign operates in a real currency, the returned value is converted from the campaign's currency to units and mathematically rounded to the second decimal place (see the section Real currencies instead of Yandex units).

SumAvailableForTransfer

The amount available to transfer using the TransferMoney method. It is returned only if the shared account is not enabled. It may be less than the campaign balance.

The value is in Yandex units.

If the campaign operates in a real currency, the returned value is converted from the campaign's currency to units and mathematically rounded to the second decimal place (see the section Real currencies instead of Yandex units).

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:

  • Yes — Campaign has been archived.
  • No — Campaign is not in the archive.
  • Pending — The campaign is being transferred to the archive, or is being restored from the archive.
  • CurrencyConverted — The campaign was automatically archived when switching the client to using currency, and cannot be unarchived (see the section Real currencies instead of Yandex units).

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:

  • Yes — Activated.
  • Pending — Waiting for activation.
StatusModerate

Moderation result:

  • Yes — Moderator approved at least one ad.
  • No — Moderator rejected all the ads.
  • New — Ads have not been submitted for moderation (the campaign has the “Draft” status).
  • Pending — Under moderation.

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.

CampaignCurrency

The currency the campaign operates in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. If the parameter is omitted or set to NULL, it means the campaign operates in Yandex units.

SourceCampaignID ID of the unit-based source campaign, if the current campaign was created automatically when switching the client to using currency (see the section Switching to currency). Otherwise, omitted or set to NULL.
DayBudgetEnabled Daily campaign budget management is available — Yes/No.
EnableRelatedKeywords

Related keywords tool enabled — Yes/No.

ExtendedAdTitleEnabled Substituting part of the ad text in the title is enabled — Yes/No.

Examples of input data

Python

['login1', 'login2']

PHP

array('login1', 'login2')

Perl

['login1', 'login2']