get

Returns the parameters of campaigns that match the specified criteria.

  1. Restrictions
  2. Request
  3. Response
Attention. All monetary campaign parameters (daily budget, weekly budget, and average price for automatic strategies) are passed via the Yandex.Direct API as integer numbers. The passed value is a monetary value in the advertiser's currency, multiplied by 1,000,000.

Restrictions

The method returns a maximum of 10,000 objects.

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* CampaignsSelectionCriteria */
      "Ids": [(long), ... ],
      "Types": [( "TEXT_CAMPAIGN" | "MOBILE_APP_CAMPAIGN" | "DYNAMIC_TEXT_CAMPAIGN" | "CPM_BANNER_CAMPAIGN" ), ... ],
      "States": [( "ARCHIVED" | "CONVERTED" | "ENDED" | "OFF" | "ON" | "SUSPENDED" ), ... ],
      "Statuses": [( "ACCEPTED" | "DRAFT" | "MODERATION" | "REJECTED" ), ... ],
      "StatusesPayment": [( "DISALLOWED" | "ALLOWED" ), ... ]
    }, /* required */
    "FieldNames": [( "BlockedIps" | ... | "Type" ), ... ], /* required */
    "TextCampaignFieldNames": [( "CounterIds" | "RelevantKeywords" | "Settings" | "BiddingStrategy" ), ... ],
    "MobileAppCampaignFieldNames": [( "Settings" | "BiddingStrategy" ), ... ],
    "DynamicTextCampaignFieldNames": [( "CounterIds" | "Settings" | "BiddingStrategy" ), ... ]
    "CpmBannerCampaignFieldNames": [( "CounterIds" | "FrequencyCap" | "Settings" | "BiddingStrategy" ), ... ]
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteriaCampaignsSelectionCriteria

Campaign selection criteria.

To get all of an advertiser's campaigns, leave SelectionCriteria empty.

Yes
FieldNamesarray of CampaignFieldEnumNames of parameters to get that are common to all types of campaigns.Yes
TextCampaignFieldNamesarray of TextCampaignFieldEnumNames of parameters to get for a “Text & Image Ads” campaign. See Campaign type.
Note. If a different type of campaign is selected according to SelectionCriteria, parameters from TextCampaignFieldNames are not returned.
No
MobileAppCampaignFieldNamesarray of MobileAppCampaignFieldEnumNames of parameters to get for an “Ads for mobile apps” campaign. See Campaign type.
Note. If a different type of campaign is selected according to SelectionCriteria, parameters from MobileAppCampaignFieldNames are not returned.
No
DynamicTextCampaignFieldNamesarray of DynamicTextCampaignFieldEnumThe names of parameters to get for a campaign with the “Dynamic ads” type. See Campaign type.
Note. If a different type of campaign is selected according to SelectionCriteria, parameters from DynamicTextCampaignFieldNames are not returned.
No
CpmBannerCampaignFieldNamesarray of CpmBannerCampaignFieldEnumNames of the parameters to get for a “Display campaign”. See Campaign type.
Note. If a different type of campaign is selected according to SelectionCriteria, parameters from CpmBannerCampaignFieldNames are not returned.
No
PageLimitOffset

Structure that defines the page for paginated selection of data.

No
CampaignsSelectionCriteria structure
Idsarray of longSelects campaigns with the specified IDs. Maximum of 1000 items in the array.No
Typesarray of CampaignTypeEnumSelects campaigns of the specified types. See Campaign type.No
Statesarray of CampaignStateEnum

Selects campaigns with the specified states. For a description of the states, see the section Campaign status and state.

Note. The get method returns a campaign in the CONVERTED state only if the States parameter is set to CONVERTED or the ID of this campaign is specified in the Ids parameter. If the Ids and States parameters are both omitted, the method doesn't return a campaign in the CONVERTED state.
No
Statusesarray of CampaignStatusSelectionEnumSelects campaigns with the specified statuses. For a description of the statuses, see the section Campaign status and state.No
StatusesPaymentarray of CampaignStatusPaymentEnumSelects campaigns with the specified payment statuses. For a description of the statuses, see the section Campaign status and state.No

Response

Response structure in JSON format:

{
  "result": { /* result */
    "Campaigns": [{  /* CampaignGetItem */
      "Id": (long),
      "Name": (string),
      "StartDate": (string),
      "Type": ( "TEXT_CAMPAIGN" | "MOBILE_APP_CAMPAIGN" |  "DYNAMIC_TEXT_CAMPAIGN" | "UNKNOWN" ),
      "Status": ( "ACCEPTED" | "DRAFT" | "MODERATION" | "REJECTED" | "UNKNOWN" ),
      "State": ( "ARCHIVED" | "CONVERTED" | "ENDED" | "OFF" | "ON" | "SUSPENDED" | "UNKNOWN" ),
      "StatusPayment": ( "DISALLOWED" | "ALLOWED" ),
      "StatusClarification": (string),
      "SourceId": (long), /* nillable */
      "Statistics": {  /* Statistics */
        "Clicks": (long), /* required */
        "Impressions": (long) /* required */
      },
      "Currency": ( "RUB" | ... | "USD" ),
      "Funds": {  /* FundsParam */
        "Mode": ( "CAMPAIGN_FUNDS" | "SHARED_ACCOUNT_FUNDS" ), /* required */
        "CampaignFunds": {  /* CampaignFundsParam */
          "Sum": (long), /* required */
          "Balance": (long), /* required */
          "BalanceBonus": (long), /* required */
          "SumAvailableForTransfer": (long)
        },
        "SharedAccountFunds": {  /* SharedAccountFundsParam */
          "Refund": (long),
          "Spend": (long)
        }
      },
      "RepresentedBy": {  /* CampaignAssistant */
        "Manager": (string), /* nillable */
        "Agency": (string) /* nillable */
      },
      "DailyBudget": {  /* DailyBudget */
        "Amount": (long), /* required */
        "Mode": ( "STANDARD" | "DISTRIBUTED" ) /* required */
      }, /* nillable */
      "EndDate": (string), /* nillable */
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "BlockedIps": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "ExcludedSites": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "TextCampaign": {  /* TextCampaignGetItem */
        ... text campaign params ...
      },
      "MobileAppCampaign": {  /* MobileAppCampaignGetItem */
        ... mobile app campaign params ...
      },
      "DynamicTextCampaign": {  /* DynamicTextCampaignGetItem */
        ... dynamic text campaign params ...
      },
      "CpmBannerCampaign": {  /* CpmBannerCampaignGetItem */
        ... cpm banner campaign params ...
      },
      "ClientInfo": (string),
      "Notification": {  /* Notification */
        "SmsSettings": {  /* SmsSettings */
          "Events": [( "MONITORING" | ... | "FINISHED" ), ... ],
          "TimeFrom": (string),
          "TimeTo": (string)
        },
        "EmailSettings": {  /* EmailSettings */
          "Email": (string),
          "CheckPositionInterval": (int),
          "WarningBalance": (int),
          "SendAccountNews": ( "YES" | "NO" ),
          "SendWarnings": ( "YES" | "NO" )
        }
      },
      "TimeTargeting": {  /* TimeTargeting */
        "Schedule": {  /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "ConsiderWorkingWeekends": ( "YES" | "NO" ), /* required */
        "HolidaysSchedule": {  /* TimeTargetingOnPublicHolidays */
          "SuspendOnHolidays": ( "YES" | "NO" ), /* required */
          "BidPercent": (int),
          "StartHour": (int),
          "EndHour": (int)
        } /* nillable */
      },
      "TimeZone": (string)
    }, ... ],
    "LimitedBy": (long)
  }
}
ParameterTypeDescription
Result structure (for JSON) / GetResponse (for SOAP)
Campaignsarray of CampaignGetItemCampaigns.
LimitedBylongSequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See the section Paginated data selection.
CampaignGetItem structure
IdlongThe campaign ID.
NamestringCampaign name (maximum of 255 characters).
ClientInfostringClient name (maximum of 255 characters). The default value is the name from the advertiser's settings.
StartDatestring

Start date for displaying ads, in the format YYYY-MM-DD. Can't be earlier than the current date.

Ad displays begin at 00:00 Moscow time (regardless of the TimeZone parameter). The start time for displays is affected by the time targeting settings (the TimeTargeting parameter).

Ad displays are possible only if at least one ad has passed review and funds have been credited to the campaign or shared account.

EndDatestring, nillableEnd date for displaying ads, in the format YYYY-MM-DD. Ad displays end at 24:00 Moscow time (regardless of the TimeZone parameter).
TimeTargetingTimeTargetingSettings for time targeting and hourly bid adjustments. Specified for the time zone specified in the TimeZone parameter.
TimeZonestring

Time zone of the advertiser's location. Use the Dictionaries.get method to get a reference list of time zones.

The default value is Europe/Moscow.

NegativeKeywordsArrayOfString, nillable

Array of negative keywords that are shared by all the keywords of a campaign.

Restriction. This parameter is not supported for campaigns with the “Display campaign” type.

A keyword should be specified without the minus sign before the first word.

Maximum of 7 words per keyword. The maximum length of each word is 35 characters. The maximum combined length of negative keywords in the array is 20,000 characters. Spaces, dashes, and operators are not counted as part of the total length.

BlockedIpsArrayOfString, nillableArray of IP addresses that campaign ads should not be shown to. Maximum of 25 items in the array.
ExcludedSitesArrayOfString, nillable

Array of display places where the ad shouldn't be displayed:

  • Domain names of websites.

  • IDs of mobile apps (the bundle ID for iOS, or the package name for Android).

  • Names of ad exchanges (SSPs). You can get a list of names using the Dictionaries.get method.

Maximum of 1000 items in the array. Maximum of 255 characters per array item.

DailyBudgetDailyBudget, nillable

Settings for the daily budget of the campaign.

Daily budget management is available if a manual display strategy is selected in the campaign. Otherwise, an attempt to set the daily budget results in an error.

NotificationNotificationSettings for SMS and email notifications.
TypeCampaignTypeGetEnumType of campaign. See Campaign type.
StatusStatusEnumStatus of the campaign. See Campaign status and state.
StateCampaignStateGetEnumCampaign state. See Campaign status and state.
StatusPaymentCampaignStatusPaymentEnumCampaign payment status. For a description of the statuses, see the section Campaign status and state.
StatusClarificationstringText explanation of the status.
SourceIdlong, nillableID of the unit-based source campaign, if the current campaign was created automatically when switching the advertiser to using currency.
StatisticsStatisticsStatistics for displays and clicks since the campaign was launched.
CurrencyCurrencyEnum

Campaign currency. Coincides with the advertiser's currency for all campaigns except campaigns in Yandex units that had copies made when the advertiser switched to working in a real currency.

To get the list of currencies, use the Dictionaries.get method.

FundsFundsParamFinancial indicators of the campaign.
RepresentedByCampaignAssistantThe Yandex personal manager or agency handling the campaign.
TextCampaignTextCampaignGetItemSettings for campaigns with the type “Text & Image Ads”. For a description of the data structure, see the section get: TextCampaign parameters.
MobileAppCampaignMobileAppCampaignGetItemSettings for campaigns with the type “Ads for mobile apps”. For a description of the data structure, see the section get: MobileAppCampaign parameters.
DynamicTextCampaignDynamicTextCampaignGetItemSettings for campaigns with the “Dynamic ads” type. For a description of the data structure, see the section get: DynamicTextCampaign parameters.
CpmBannerCampaignCpmBannerCampaignGetItemSettings for a campaign with the “Display campaign” type. For a description of the data structure, see the section get: CpmBannerCampaign parameters.
TimeTargeting structure
ScheduleArrayOfString

Settings for time targeting and hourly bid adjustments. Maximum of 7 items in the array.

Each array item contains 25 comma-separated numbers. The first number is the number of the day of the week: from 1 (Monday) to 7 (Sunday). The next 24 numbers are a sequence of bid coefficients for displaying ads in the corresponding hours. Coefficients are specified as percentages from 0 to 200. The value must be a multiple of 10: The coefficient 0 means that ads are not displayed during this hour. Example of an array element: 1,0,0,50,50,100,100,150,200,200,150,100,100,80,70,100,100,100,50,50,40,30,0,0,0

Note.
  • If the array is missing an element for one of the days of the week, all the bid coefficients are set to 100 for this day.
  • If an automatic display strategy is selected, the coefficient 0 means displays are not allowed, and any other coefficient means displays are allowed (in other words, it is equivalent to 100).
ConsiderWorkingWeekendsYesNoEnum

Whether to change the display schedule when a work day is moved to Saturday or Sunday because of a public holiday.

For example, if a work day is moved from Monday to Saturday and the value is YES, on the Saturday work day, ads are displayed according to the Monday schedule, and on the Monday holiday, they are displayed according to the Saturday schedule.

HolidaysScheduleTimeTargetingOnPublicHolidays, nillable

Display settings on public holidays.

If the time zone specified in the TimeZone parameter belongs to Russia, Ukraine, Belarus, Kazakhstan, or Turkey, we use the holiday calendar for the appropriate country. In all other cases, we use the Russian calendar.

TimeTargetingOnPublicHolidays structure
SuspendOnHolidaysYesNoEnum

Whether to suspend ads on public holidays: YES — suspend; NO — don't suspend.

Note. The BidPercent, StartHour and EndHour parameters can only be set when SuspendOnHolidays has the value NO.
BidPercentintThe bid coefficient for displays on public holidays. Specified as a percentage from 0 to 200. The value must be a multiple of 10:
StartHourintThe time (in hours) to start displays on public holidays. From 0 to 23.
EndHourintThe time (in hours) to end displays on public holidays. From 0 to 24.
DailyBudget structure
Amountlong

The daily campaign budget in the advertiser's currency, multiplied by 1,000,000.

The minimum daily budget for each currency is listed in the currency reference. To get the list of currencies, use the Dictionaries.get method.

ModeDailyBudgetModeEnum

Mode for displaying ads:

  • STANDARD — standard
  • DISTRIBUTED — distributed

See the Daily budget section under “Manual management” in the Help for Yandex.Direct.

Notification structure
SmsSettingsSmsSettings

Settings for sending SMS notifications. The phone number to send notifications to is taken from the advertiser's Yandex profile (see the section My numbers in the Help for Yandex.Passport).

EmailSettingsEmailSettingsSettings for sending email notifications.
SmsSettings structure
Eventsarray of SmsEventsEnum
Events to notify of by SMS:
  • MONITORING — Pausing and resuming ad displays by site availability monitoring using Metrica data.
  • MODERATION — Ads accepted or rejected after review.
  • MONEY_IN — Funds deposited to the campaign balance (not used when a shared account is enabled).
  • MONEY_OUT — Funds used up on the campaign balance (not used when a shared account is enabled).
  • FINISHED — End of the campaign.
TimeFromstring

The allowed starting time for sending SMS notifications of campaign events. Specified in the format HH:MM; minutes are set in multiples of 15 (0, 15, 30, 45). For example, 19:45.

The default value is 9:00.

TimeTostring

The ending time for sending SMS notifications of campaign events. Specified in the format HH:MM; minutes are set in multiples of 15 (0, 15, 30, 45). For example, 19:45.

The default value is 21:00.

EmailSettings structure
Emailstring

The email address for sending notifications of campaign events.

The default value is the advertiser's address.

CheckPositionIntervalint

The frequency of checking the traffic forecast: 15, 30 or 60 minutes. The default value is 60.

A notification is sent if the traffic forecast is lower than the one that the bid covered at the time of configuration.

WarningBalanceint

The minimal balance; notification is sent when the account balance is reduced to this amount. Set as a percentage of the amount of the last payment, from 1 to 50. The default value is 20.

If the client has the shared account enabled, this parameter is not used.

SendAccountNewsYesNoEnum

Whether to send notifications of events related to the campaign. It is set for campaigns that have a personal Yandex manager. For campaigns that are not handled by a personal manager, the passed value is ignored. The default value is NO.

SendWarningsYesNoEnumWhether to send email notifications. The default value is NO.
Statistics structure
ImpressionslongThe number of impressions since the campaign was launched.
ClickslongThe number of clicks since the campaign was launched.
FundsParam structure
ModeCampaignFundsEnum

Type of financial indicators for the campaign:

  • CAMPAIGN_FUNDS — The shared account is not enabled, and financial indicators are returned in the CampaignFund child structure.
  • SHARED_ACCOUNT_FUNDS — The shared account is enabled, and financial indicators are returned in the SharedAccountFund child structure.
CampaignFundsCampaignFundsParamThe campaign's financial indicators, if the shared account is not enabled.
SharedAccountFundsSharedAccountFundsParamThe campaign's financial indicators, if the shared account is enabled.
CampaignFundsParam structure
SumlongThe amount of funds credited to the campaign balance since the campaign was launched, in the advertiser's currency without VAT.
BalancelongThe current balance of the campaign, in the advertiser's currency without VAT.
BalanceBonuslongDiscount bonus. This parameter is no longer relevant.
SumAvailableForTransferlongThe amount available for transferring to another campaign, in the advertiser's currency without VAT.
SharedAccountFundsParam structure
RefundlongThis parameter is obsolete. Always returns 0.
SpendlongThe amount of funds spent on this campaign since its launch, in the advertiser's currency without VAT.
CampaignAssistant structure
Managerstring, nillableThe name of the Yandex personal manager (for campaigns that are handled by a personal manager).
Agencystring, nillableThe name of the advertising agency (for campaigns that are handled by an agency).