check

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

  1. Request
  2. Response
  3. Examples

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 Required
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. Either CampaignIds, 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
Parameter Type Description Required
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. Either CampaignIds, 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.
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.