check

Informs you of changes in the client's campaigns, groups, and ads, starting from the specified date.

Learn more

Request

Request structure in JSON format:

{
  "method": "check",
  "params": { /* params */
    "CampaignIds": [(long), ... ],
    "AdGroupIds": [(long), ... ],
    "AdIds": [(long), ... ],
    "Timestamp": (string), /* required */
    "FieldNames": [( "CampaignIds" | "AdGroupIds" | "AdIds" | "CampaignsStat" ), ... ] /* required */
  }
}

Parameter

Type

Description

Mandatory

params structure (for JSON) / CheckRequest structure (for SOAP)

CampaignIds

array of long

IDs of the campaigns to check for changes. From 1 to 3000 items in the array.

Use either CampaignIds, or AdGroupIds, or AdIds

AdGroupIds

array of long

IDs of the groups to check for changes. From 1 to 10,000 items in the array.

AdIds

array of long

IDs of the ads to check for changes. From 1 to 50,000 items in the array.

FieldNames

array of FieldNamesEnum

Which types of changes to check for:

  • CampaignIds — Changes in campaign parameters (not including changes in child groups, ads, and keywords).
  • CampaignsStat — Corrected campaign statistics (usually related to filtering out false clicks).
  • AdGroupIds — Changes in ad groups and keywords (not including changes in ads).
  • AdIds — Changes to ads.

Changes are checked for all related objects. For example, if the request specifies the AdIds input parameter and the CampaignIds value in the FieldNames array, it checks for changes in campaigns that the specified ads belong to. For more information, see Examples.

Yes

Timestamp

string

The exact time to start from to check for changes. Specified in YYYY-MM-DDThh:mm:ssZ format (conforming to ISO 8601), such as 2015-05-24T23:59:59Z.

Yes

Note

The parameters CampaignIds, AdGroupIds and AdIds are mutually exclusive. Only one of them can be included in the request.

Response

Response structure in JSON format:

{
  "result": { /* result */
   "Modified": {  /* CheckResponseModified */
      "CampaignIds": [(long), ... ],
      "AdGroupIds": [(long), ... ],
      "AdIds": [(long), ... ],
      "CampaignsStat": [{  /* CampaignStatItem */
        "CampaignId": (long), /* required */
        "BorderDate": (string) /* required */
       }, ... ]
   },
   "NotFound": {  /* CheckResponseIds */
      "CampaignIds": [(long), ... ],
      "AdGroupIds": [(long), ... ],
      "AdIds": [(long), ... ]
   },
   "Unprocessed": {  /* CheckResponseIds */
      "CampaignIds": [(long), ... ],
      "AdGroupIds": [(long), ... ],
      "AdIds": [(long), ... ]
   },
   "Timestamp": (string)
  }
}

Parameter

Type

Description

result structure (for JSON) / CheckResponse structure (for SOAP)

Modified

CheckResponseModified

Objects specified in the request or associated with them that had changes.

NotFound

CheckResponseIds

Objects specified in the request that were not found.

Unprocessed

CheckResponseIds

Objects specified in the request that were not processed. For these objects, you should make a separate request.

Timestamp

string

The exact time when changes were checked. Specified in YYYY-MM-DDThh:mm:ssZ format (conforming to ISO 8601), such as 2015-05-24T23:59:59Z. The timestamp is specified in the next method call, to check for changes starting from this time.

CheckResponseModified structure

CampaignIds

array of long

IDs of campaigns that had changes in the parameters (changes in child objects and ads do not count).

AdGroupIds

array of long

IDs of groups that had changes (includes changes in keywords, but changes in ads do not count).

AdIds

array of long

IDs of ads that had changes.

CampaignsStat

array of CampaignStatItem

Campaigns that had statistics corrected.

CampaignStatItem structure

CampaignId

long

The campaign ID.

BorderDate

string

Date when statistics were current. Output only for campaigns with statistics that were adjusted during the period being checked. Adjustments of statistics are usually due to filtering out false clicks and lead to a reduction in the number of clicks and an increase in the campaign balance.

Statistics reports that were generated earlier may turn out to be inaccurate if they show data after BorderDate. We recommend re-creating such reports.

CheckResponseIds structure

CampaignIds

array of long

IDs of campaigns.

AdGroupIds

array of long

Group IDs.

AdIds

array of long

IDs of ads.

Examples

Checks for changes in groups and keywords for the specified campaigns
{
  "method": "check",
  "params": {
    "CampaignIds": [13765,13767],
    "FieldNames": ["AdGroupIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "AdGroupIds": [23543,23544,23874]
    }
    "Timestamp": "2015-02-02T12:23:11Z"
  }
}

Comments: changes were made in three groups (or keywords in these groups).

Checks for changes in the set campaigns and their child groups and ads
{
  "method": "check",
  "params": {
    "CampaignIds": [13765,13766,13767,13769],
    "FieldNames": ["CampaignIds","CampaignsStat","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [13767,13769],
      "AdGroupIds": [23543,23544,23874],
      "AdIds": [33651,33921,34028,34106],
      "CampaignsStat": [
        {
          "CampaignId": 13767,
          "BorderDate": "2015-01-28"
        }
      ]
    },
    "NotFound": {
      "CampaignIds": [13765]
    },
    "Timestamp": "2015-02-02T12:23:11Z"
  }
}

Comments: changes were made in two campaigns, three child groups (or keywords in these groups), and four child ads. Statistics were adjusted in one campaign. One campaign was not found.

Checks for changes in the set ads and their parent groups and campaigns
{
  "method": "check",
  "params": {
    "AdIds": [33651,33732,34028,34029],
    "FieldNames": ["CampaignIds","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [13767],
      "AdGroupIds": [],
      "AdIds": [33651,34028]
    },
    "NotFound": {
      "AdIds": [33732]
    },
    "Timestamp": "2015-02-02T12:25:19Z"
  }
}

Comments: changes were made to two ads and one campaign, which contains one or more ads specified in the request. One ad was not found.

Checks for changes in the set group and ads in the group, as well as in the parent campaign
{
  "method": "check",
  "params": {
    "AdGroupIds": [23764],
    "FieldNames": ["CampaignIds","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T10:08:22Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [],
      "AdGroupIds": [],
      "AdIds": [33651,34028]
    },
    "Timestamp": "2015-02-02T12:25:19Z"
  }
}

Comments: no changes were made in the group (or this group's keywords), or in the parent campaign. There were changes to two ads from the group.

Checks for changes in the set groups and ads in the groups, as well as in parent campaigns
{
  "method": "check",
  "params": {
    "AdGroupIds": [23543,23544,23874],
    "FieldNames": ["CampaignIds","AdGroupIds","AdIds"],
    "Timestamp": "2015-02-02T12:25:19Z"
  }
}

Response:

{
  "result": {
    "Modified": {
      "CampaignIds": [13767],
      "AdGroupIds": [23543],
      "AdIds": [33651,33732,34028,34029,33921,34028,34106]
    },
    "Unprocessed": {
      "AdGroupIds": [23544,23874]
    },
    "Timestamp": "2015-02-02T14:51:40Z"
  }
}

Comments: changes were made to one group (or keywords in this group), the campaign this group belongs to, and seven of the group's ads. Two groups were not processed: they might have also had changes, so a separate request is necessary.