campaign

Get a list of campaigns.

Request format

Note

https://adfox.yandex.com/api/v1
  ? object=account
  & action=list
  & actionObject=campaign
  & [actionObjectID=<integer>]
  & [superCampaignID=<integer>]
  & [dateAddedFrom=<YYYY-MM-DD>]
  & [dateAddedTo=<YYYY-MM-DD>]
  & [show=<string>]
  & [search=<string>]
  & [criteriaID=<integer>]
  & [showMode=<string>]

`actionObjectID`	To get data for only one campaign, specify its ID. Default value: `0` (display the list of all campaigns).
`superCampaignID`	Filter by supercampaign ID.
`dateAddedFrom`	Data filtering: show campaigns created after the specified date. Date format: `YYYY-MM-DD`
`dateAddedTo`	Data filtering: show campaigns created before the specified date. Date format: `YYYY-MM-DD`
`show`	This parameter is used to specify the degree of data completeness in the list of campaigns and to display the targeting settings of a certain campaign. Configuring data completeness in the list of campaigns: Acceptable values: `common` (brief display format): ID. name. `short` (limited display format): ID. name. superCampaignID. status. dateStart. dateEnd. dateFinished. `advanced` (full display format). Default value: `advanced`. Configuring the display of targeting settings of a certain campaign: Required parameter: `actionObjectID`. Forbidden: `dateAddedFrom`, `dateAddedTo`, and `search`. Acceptable values: `targetingTime`: Targeting by time. `targetingFrequency`: Targeting by frequency. `targetingBehavior`: Targeting by behavior. `targetingGeobase`: Targeting by geography. `targetingSearch`: Targeting by search queries. `targetingGender`: Targeting by gender. `targetingAge`: Targeting by age. `targetingRevenue`: Targeting by income. `targetingUser`: Additional targeting. Additional parameters: criteriaID and showMode.
`search`	Filtering by substring in a supercampaign name. An entry can contain Russian and Latin letters, numbers, and any special characters
`criteriaID`	Only required for getting data on custom targeting (show=targetingUser). User characteristic ID. Acceptable values: from `1` to `63`.
`showMode`	Only used for getting data on custom targeting (show=targetingUser). You can use it to display the list of allowed and/or prohibited values of a specified user characteristic in the ad campaign. Acceptable values: `denied`: Only show prohibited values. `allowed`: Only show allowed values. `all`: Show all values with a breakdown into allowed and prohibited ones. Default value: `denied`.

* Required parameter

Response format

<response>
<status>
    <code>{integer}</code>
</status>
<data>
<result>
  <row0>
    <ID>{integer}</ID>
    <name>{string}</name>
    <superCampaignID>{integer}</superCampaignID>
    <superCampaignName>{string}</superCampaignName>
    <advertiserID>{integer}</advertiserID>
    <advertiserAccount>{string}</advertiserAccount>
    <assistantID>{integer}</assistantID>
    <assistantAccount>{string}</assistantAccount>
    <additionalAdvertiserIDs>{integer}</additionalAdvertiserIDs>
    <additionalAdvertiserAccounts>{string}</additionalAdvertiserAccounts>
    <additionalAssistantIDs>{integer}</additionalAssistantIDs>
    <additionalAssistantAccounts>{string}</additionalAssistantAccounts>
    <status>{integer}</status>
    <level>{integer}</level>
    <priority>{integer}</priority>
    <targetingProfileID>{integer}</targetingProfileID>
    <isSession>{integer}</isSession>
    <impressionsMethodID>{integer}</impressionsMethodID>
    <impressionsSmoothTypeID>{integer}</impressionsSmoothTypeID>
    <kind_id>{integer}</kind_id>
    <sectorID>{integer}</sectorID>
    <rotationMethodID>{integer}</rotationMethodID>
    <trafficPercents>{integer}</trafficPercents>
    <logicType>{integer}</logicType>
    <cpm>{integer}</cpm>
    <cpc>{integer}</cpc>
    <isTrafficSmooth>{integer}</isTrafficSmooth>
    <maxImpressions>{integer}</maxImpressions>
    <maxClicks>{integer}</maxClicks>
    <impressionsAll>{integer}</impressionsAll>
    <clicksAll>{integer}</clicksAll>
    <impressionsToday>{integer}</impressionsToday>
    <clicksToday>{integer}</clicksToday>
    <maxImpressionsPerDay>{integer}</maxImpressionsPerDay>
    <maxClicksPerDay>{integer}</maxClicksPerDay>
    <maxImpressionsPerHour>{integer}</maxImpressionsPerHour>
    <maxClicksPerHour>{integer}</maxClicksPerHour>
    <impressionsPerHour>{integer}</impressionsPerHour>
    <clicksPerHour>{integer}</clicksPerHour>
    <dateStart>{date}</dateStart>
    <dateEnd>{date}</dateEnd>
    <dateFinished>{date}</dateFinished>
    <dateAdded>{date}</dateAdded>
    <common_profile_id>{integer}</common_profile_id>
    <costType>{integer}</costType>
    <sendToErir>{integer}</sendToErir>
      <contractID>{integer}</contractID>
      <publisherContractID>{integer}</publisherContractID>
      <markingAdvertiserInfo>{string}</markingAdvertiserInfo>
  </row0>
</result>
</data>
</response>

Response parameters

`code`	Request processing status. A value of `0` means the request was completed successfully. For the key, see Error handling.
`rows`	Number of items in the response tree.
`rowN`	Item number in the response tree, where N is a number from 0 to rows-1 (where “rows” is the total number of items in the response).
`ID`	Unique ID of the campaign.
`name`	Campaign name.
`superCampaignID`	ID of the supercampaign that the campaign belongs to.
`superCampaignName`	Name of the supercampaign that the campaign belongs to.
`advertiserID`	Advertiser ID.
`advertiserAccount`	Advertiser's account.
`assistantID`	ID of the assistant that the campaign is assigned to.
`assistantAccount`	Account of the assistant that the campaign is assigned to.
`additionalAdvertiserIDs`	IDs of additional advertisers.
`additionalAdvertiserAccounts`	Accounts of additional advertisers.
`additionalAssistantIDs`	IDs of additional assistants.
`additionalAssistantAccounts`	Accounts of additional assistants.
`level`	Campaign level.
`priority`	Campaign priority.
`status`	Status. Acceptable values: `0`: Active. `1`: Suspended. `2`: Completed.
`type`	Deprecated parameter. Campaign type. Acceptable values: `0`: Simplified. `1`: Standard.
`tracingPointsType`	Deprecated parameter. Action tracking. Acceptable values: `0`: No. `1`: postClick. `2`: postView & postClick. `3`: postView.
`targetingProfileID`	Targeting profile ID.
`isSession`	Session impressions. Acceptable values: `0`: Disabled. `1`: Enabled.
`bannerSequence`	Deprecated parameter. Creative selection method. Acceptable values: `0`: by weight. Banners are selected based on their priority. `1`: Sequential (the “Scenario period” (scenarioPeriodID) parameter is required). A script (scenario) indicates the banner number and how many times it's served to the user.
`scenarioPeriodID`	Deprecated parameter. The scenario period determines the frequency of repeated banner impressions in this ad campaign for a unique user. It's required if banners are selected sequentially (`bannerSequence=1`). Acceptable values: `0`: a one-time scenario. `1`: 1 hour. `2`: 4 hours. `3`: 6 hours. `4`: 12 hours. `5`: 24 hours. `6`: 1 week. `7`: A month. `11`: a looping sequence.
`impressionsMethodID`	Impression count method. Acceptable values: `0`: Banner ad response. An impression is counted when the banner code is uploaded to the site page. `101≤N≤130`, where N is the ordinal number of the event from 1 to 30 (the value 101 corresponds to event 1, the value 105 corresponds to event 5, and so on). An impression is counted when the event with the specified number is called by the banner on the site page. `1101`: Viewable impression, Yandex (IMS). To count as an impression, at least 50% of the banner must be visible in the active browser window for at least two seconds. `2101`: Impression (IMS). An impression event that occurs when ad rendering begins. `2102`: Viewable impression (IMS). Ad impressions are counted as viewable when they meet criteria established by international media industry standards, including a minimum percentage of pixels within the browser's viewable area and a minimum duration of visibility within that area.
`impressionsSmoothTypeID`	Deliver impressions. Acceptable values: `0`: As fast as possible. Campaign banners are served at the maximum possible speed until the impression limits are reached (if specified). The maximum delivery speed doesn't require you to set limits or specify the campaign start and end dates. `1`: Spread evenly throughout the day. Impressions are uniformly distributed throughout the day. Make sure to specify the maximum number of impressions per day (`maxImpressionsPerDay`). `2`: Spread evenly throughout the entire period. The campaign impressions are distributed evenly over the entire period based on account statistics. Make sure to specify the maximum number of impressions (`maxImpressions`) and the ad campaign end date (`dateEnd`). `3`: Spread evenly throughout the entire period (automatic prolongation). The campaign impressions are distributed evenly over the entire period based on account statistics. If the campaign doesn't run over its limit in the allocated time, it's automatically extended for 1 day and runs at maximum speed on that day. Make sure to specify the maximum number of impressions (`maxImpressions`) and the ad campaign end date (`dateEnd`). `4`: Maximum at the beginning of campaign delivery. Impressions are distributed unevenly: the system schedules more impressions in the first days of placement and gradually decreases them toward the end of the campaign. This reduces the risk of campaign underdelivery if the available inventory gets unexpectedly limited at the end of the campaign period. Make sure to specify the maximum number of impressions (`maxImpressions`) and the ad campaign end date (`dateEnd`).
`kind_id`	Defines the campaign type. Acceptable values: `1`: Guarantee type. It's used for campaigns with guaranteed sales where there are ad running obligations. `2`: Dynamic monetization type. `3`: Promo type. It's used for custom promotion campaigns and placeholders.
`sectorID`	Industry. For more information on how to get the list of industries, see utility-sector.
`rotationMethodID`	Campaign rotation method. Acceptable values: `0`: By priority. `1`: By % of traffic.
`trafficPercents`	Traffic percentage.
`logicType`	Campaign type. Acceptable values: `0`: Commercial. `1`: Measuring campaign.
`cpm`	CPM threshold for a Dynamic monetization campaign.
`cpc`	CPC threshold value for an ad campaign of the Dynamic monetization type.
`maxImpressions`	Maximum number of impressions.
`impressionsAll`	Data from counters. Total number of impressions.
`maxImpressionsPerDay`	Maximum number of impressions per day.
`impressionsToday`	Data from counters. Number of impressions on the current day.
`maxImpressionsPerHour`	Maximum number of impressions per hour.
`impressionsPerHour`	Data from counters. Number of impressions in the current hour.
`maxClicks`	Maximum total number of clicks.
`clicksAll`	Data from counters. Total number of clicks.
`maxClicksPerDay`	Maximum number of clicks per day.
`clicksToday`	Data from counters. Number of clicks on the current day.
`maxClicksPerHour`	Maximum number of clicks per hour.
`clicksPerHour`	Data from counters. Number of clicks in the current hour.
`dateStart`	Ad running start date.
`dateEnd`	Delivery end date.
`dateFinished`	Delivery completion date.
`dateAdded`	Add date.
`common_profile_id`	General profile ID for `show=advanced`.
`costType`	Campaign type. Acceptable values: `0`: Other. `1`: CPM. `2`: CPC. `3`: CPA.
`sendToErir`	Submit data to the state register (ERIR). Acceptable values: `0`: Do not submit data to the state register. `1`: Submit data to state register (labeling enabled).
`contractID`	ID of a direct or primary contract.
`publisherContractID`	ID of the contract with the end advertiser.
`okveds`	Deprecated parameter. The business activity code (OKVED) for the advertised product.
`markingAdvertiserInfo`	Advertiser information as shown in the banner menu.

Sample request and response

Request:

https://adfox.yandex.com/api/v1?object=account&action=list&actionObject=campaign

Response:

<response>
<status>
  <code>0</code>
</status>
<data>
<result>
  <row0>
    <ID>474205</ID>
    <name>example</name>
    <superCampaignID/>
    <superCampaignName/>
    <advertiserID>226201</advertiserID>
    <advertiserAccount>ivanov</advertiserAccount>
    <assistantID>239097</assistantID>
    <assistantAccount>petrov</assistantAccount>
    <additionalAdvertiserIDs/>
    <additionalAdvertiserAccounts/>
    <additionalAssistantIDs/>
    <additionalAssistantAccounts/>
    <status>0</status>
    <level>1</level>
    <priority>100</priority>
    <targetingProfileID>0</targetingProfileID>
    <isSession>0</isSession>
    <impressionsMethodID>0</impressionsMethodID>
    <impressionsSmoothTypeID>0</impressionsSmoothTypeID>
    <kind_id>0</kind_id>
    <sectorID>0</sectorID>
    <rotationMethodID>0</rotationMethodID>
    <trafficPercents>0</trafficPercents>
    <logicType>0</logicType>
    <cpm>0</cpm>
    <cpc>0</cpc>
    <isTrafficSmooth>0</isTrafficSmooth>
    <maxImpressions>0</maxImpressions>
    <maxClicks>0</maxClicks>
    <impressionsAll>0</impressionsAll>
    <clicksAll>0</clicksAll>
    <impressionsToday>0</impressionsToday>
    <clicksToday>0</clicksToday>
    <maxImpressionsPerDay>0</maxImpressionsPerDay>
    <maxClicksPerDay>0</maxClicksPerDay>
    <maxImpressionsPerHour>0</maxImpressionsPerHour>
    <maxClicksPerHour>0</maxClicksPerHour>
    <impressionsPerHour>0</impressionsPerHour>
    <clicksPerHour>0</clicksPerHour>
    <dateStart>2021-05-18 13:00:00</dateStart>
    <dateEnd/>
    <dateFinished>0000-00-00 00:00:00</dateFinished>
    <dateAdded>2021-05-18</dateAdded>
    <common_profile_id>525</common_profile_id>
    <costType>1</costType>
    <sendToErir>1</sendToErir>
    <contractID>139</contractID>
    <publisherContractID>50</publisherContractID>
    <markingAdvertiserInfo>Daisy LLC OGRN 1231231</markingAdvertiserInfo>
  </row0>
</result>
</data>
</response>

Other actions with the object

Read also about other actions with the campaign object:

Add a campaign.
Delete a campaign.
Edit a campaign.
Get a list of ad campaign banners.
Place a campaign on a a site, in a section, or on a placement.
Add a contractor
Add a contract.

Default value: 0 (display the list of all campaigns).

Date format: YYYY-MM-DD

Configuring data completeness in the list of campaigns:

Acceptable values:

common (brief display format):
- ID.
- name.
short (limited display format):
- ID.
- name.
- superCampaignID.
- status.
- dateStart.
- dateEnd.
- dateFinished.
advanced (full display format).

Default value: advanced.

Configuring the display of targeting settings of a certain campaign:

Required parameter: actionObjectID.

Forbidden: dateAddedFrom, dateAddedTo, and search.

Acceptable values:

targetingTime: Targeting by time.
targetingFrequency: Targeting by frequency.
targetingBehavior: Targeting by behavior.
targetingGeobase: Targeting by geography.
targetingSearch: Targeting by search queries.
targetingGender: Targeting by gender.
targetingAge: Targeting by age.
targetingRevenue: Targeting by income.
targetingUser: Additional targeting. Additional parameters: criteriaID and showMode.

An entry can contain Russian and Latin letters, numbers, and any special characters

User characteristic ID.

Acceptable values: from 1 to 63.

You can use it to display the list of allowed and/or prohibited values of a specified user characteristic in the ad campaign.

Acceptable values:

denied: Only show prohibited values.
allowed: Only show allowed values.
all: Show all values with a breakdown into allowed and prohibited ones.

Default value: denied.

Was the article helpful?

bannerType