Account Change History

The account history API provides advertisers with change history data for an account within the last three months. You can view information on the objects changed and the old and new values associated with those changes. The API lets you view and monitor a wide range of changes – for example, when a campaign was paused, who changed budgets, what bid changes were, and so on.

Five specific example JSON representations are provided here, using various filters:

  • Retrieving data for a specific account
  • Using an Object Type or Object Field filters
  • Using an Object SubType filter
  • Using a Parent campaign ID filter
  • Using an Action filter

Endpoint

Resource URI

https://api.gemini.yahoo.com/v3/rest/accounthistory/reports

Fields

Method: To read audience data, make a POST call and pass in the following parameters:

Name Description Attribute Type
Advertiser ID The ID of the advertiser to retrieve. Must be filtered string
Action The operation to filter by {CREATE,UPDATE,DELETE}. Can be filtered string
Change Date “YYYY-MM-DD” format in UTC timezone. The maximum lookback window is 3 months ago. Can be filtered string
Object ID The ID of the object (Ad, Ad Group, Advertiser, Campaign and so on) to filter by Can be filtered string
Object Type The object type(s) to filter by - {CAMPAIGN, ADGROUP, AD…} Can be filtered string
Object SubType The object subtype applicable to targeting attributes - such as Device Must be filtered string
Object Field The object field to filter by - {STATUS, NAME, TITLE, …} Can be filtered string
Campaign ID If specified, only objects belonging to the campaigns are returned. Can be filtered string
AdGroup ID If specified, only objects belonging to adgroups are returned. Can be filtered string
Max Rows The maximum number of rows to retrieve. Default is 100 and Value should not be greater than 1000.   string
Start Index The start index of the first item to retrieve.   string
Sort By The object field to sort by.   string
Sort Order The sorting order DESC or ASC   string

Example Representations

Example 1: Retrieve data for a specific account

To request account history for a particular account, make a POST call to

https://api.admanager.yahoo.com/v3/rest/accounthistory/reports

with a request body similar to the following:

{
  "filters": [
      { "field": "ChangeDate","operator": "between", "from": "2018-05-09", "to": "2018-05-10"},
      { "field": "AdvertiserID","operator": "=", "value":"1495309"}
  ]
}

Response:

{
    "errors": null,
    "timestamp": "2018-05-16 22:28:28",
    "response": {
        "rows": [
            {
                "objectId": "305151574155",
                "objectType": "TargetingAttribute",
                "objectSubType": "DEVICE",
                "objectField": "modifier",
                "advertiserId": "1495309",
                "user": "jchristensen",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525981579000,
                "action": "UPDATE",
                "oldValue": "1.47",
                "newValue": "0.53",
                "campaignId": 365691871,
                "adGroupId": null
            }
        ],
        "accountHistoryRequest": {
            "startIndex": null,
            "maxRows": null,
            "entityIds": [],
            "entityTypes": null,
            "entityAttrs": null,
            "advertiserIds": [
                1495309
            ],
            "campaignIds": [],
            "adgroupIds": [],
            "entitySubTypes": null,
            "sortAttr": null,
            "sortOrder": null,
            "userUpdates": [],
            "userType": null,
            "actions": null,
            "fromToDate": {
                "left": 1525824000,
                "right": 1525996800,
                "value": 1525996800,
                "key": 1525824000
            },
            "objectTypeFieldDataList": [
                {
                    "entityType": "AdvertiserDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "mdmAdvertiserName",
                        "tier",
                        "amContact",
                        "vatId",
                        "suspendReason",
                        "trackingUrl",
                        "channel",
                        "timezone"
                    ]
                },
                {
                    "entityType": "CampaignDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "campaignName",
                        "budget",
                        "spendCap",
                        "budgetType",
                        "trackingUrl",
                        "isNativeChannel",
                        "isSearchChannel",
                        "subChannelModifier",
                        "customParameters",
                        "biddingStrategy",
                        "startDateStr",
                        "endDateStr",
                        "subChannel"
                    ]
                },
                {
                    "entityType": "AdGroupDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "adGroupName",
                        "startDateStr",
                        "endDateStr",
                        "bidSet",
                        "ecpaGoal",
                        "biddingStrategy",
                        "customParameters",
                        "trackingUrl"
                    ]
                },
                {
                    "entityType": "AdDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "title",
                        "title2",
                        "description",
                        "imageUrl",
                        "imageUrlHQ",
                        "imageUrlLarge",
                        "impressionTrackingUrl",
                        "trackingUrl",
                        "callToActionText",
                        "contentUrl",
                        "displayUrl",
                        "landingUrl",
                        "sponsoredBy",
                        "finalUrl",
                        "displayUrlPath1",
                        "displayUrlPath2",
                        "customParameters",
                        "mobileFinalUrl"
                    ]
                },
                {
                    "entityType": "TargetingAttributeDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "exclude",
                        "targetingType",
                        "value",
                        "bidSet",
                        "adParamValues",
                        "landingUrl",
                        "customParameters",
                        "finalUrl",
                        "trackingUrl",
                        "modifier",
                        "mobileFinalUrl"
                    ]
                }
            ]
        },
        "errors": null
    }
}

Example 2: Using Object Type OR Object Field filters

Request:

{

  "filters": [
      { "field": "ChangeDate","operator": "between", "from": "2018-04-23", "to": "2018-04-24"},
      { "field": "AdvertiserID","operator": "=", "value":"1495309"},
      { "field": "ObjectType","operator": "=", "value":"Campaign"},
      { "field": "ObjectField","operator": "=", "value":"Status"}
  ]
}

Response:

{
    "errors": null,
    "timestamp": "2018-05-16 23:24:17",
    "response": {
        "rows": [
            {
                "objectId": "366588003",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "E",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1524611756000,
                "action": "CREATE",
                "oldValue": null,
                "newValue": null,
                "campaignId": null,
                "adGroupId": null
            },
            {
                "objectId": "352784252",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "E",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1524609432000,
                "action": "UPDATE",
                "oldValue": "PAUSED",
                "newValue": "ACTIVE",
                "campaignId": 352784252,
                "adGroupId": null
            },
            {
                "objectId": "352784252",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "E",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1524609429000,
                "action": "UPDATE",
                "oldValue": "ACTIVE",
                "newValue": "PAUSED",
                "campaignId": 352784252,
                "adGroupId": null
            }
        ],
        "accountHistoryRequest": {
            "startIndex": null,
            "maxRows": null,
            "entityIds": [],
            "entityTypes": [
                "CampaignDTO"
            ],
            "entityAttrs": [
                "status"
            ],
            "advertiserIds": [
                1495309
            ],
            "campaignIds": [],
            "adgroupIds": [],
            "entitySubTypes": null,
            "sortAttr": null,
            "sortOrder": null,
            "userUpdates": [],
            "userType": null,
            "actions": null,
            "fromToDate": {
                "left": 1524441600,
                "right": 1524614400,
                "value": 1524614400,
                "key": 1524441600
            },
            "objectTypeFieldDataList": [
                {
                    "entityType": "CampaignDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status"
                    ]
                }
            ]
        },
        "errors": null
    }
}

Example 3: Using Object SubType filter

Request:

{

  "filters": [
      { "field": "ChangeDate","operator": "between", "from": "2018-05-01", "to": "2018-05-17"},
      { "field": "AdvertiserID","operator": "=", "value":"1495309"},
      { "field": "ObjectSubType","operator": "=", "value":"WOEID"}
  ]
}

Response:

{
    "errors": null,
    "timestamp": "2018-05-18 0:04:07",
    "response": {
        "rows": [
            {
                "objectId": "305150823131",
                "objectType": "TargetingAttribute",
                "objectSubType": "WOEID",
                "objectField": "exclude",
                "advertiserId": "1495309",
                "user": "mjeng17",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1526516081000,
                "action": "UPDATE",
                "oldValue": "true",
                "newValue": "false",
                "campaignId": 366588003,
                "adGroupId": null,
                "requestId": "4b6cdf90-5967-11e8-b5d6-7d2d4d8fbb5c-0"
            },
            {
                "objectId": "305150823130",
                "objectType": "TargetingAttribute",
                "objectSubType": "WOEID",
                "objectField": "exclude",
                "advertiserId": "1495309",
                "user": "mjeng17",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1526516081000,
                "action": "UPDATE",
                "oldValue": "false",
                "newValue": "true",
                "campaignId": 366588003,
                "adGroupId": null,
                "requestId": "4b6cdf90-5967-11e8-b5d6-7d2d4d8fbb5c-0"
            },
            {
                "objectId": "305264712612",
                "objectType": "TargetingAttribute",
                "objectSubType": "WOEID",
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "patty7612",
                "userType": "E",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525463182000,
                "action": "CREATE",
                "oldValue": null,
                "newValue": null,
                "campaignId": 366813830,
                "adGroupId": null,
                "requestId": "d244fb30-4fd3-11e8-b51d-f777e24d087d-0"
            }
        ],
        "accountHistoryRequest": {
            "startIndex": null,
            "maxRows": null,
            "entityIds": [],
            "entityTypes": [
                "TargetingAttributeDTO"
            ],
            "entityAttrs": null,
            "advertiserIds": [
                1495309
            ],
            "campaignIds": [],
            "adgroupIds": [],
            "entitySubTypes": [
                "WOEID"
            ],
            "sortAttr": null,
            "sortOrder": null,
            "userUpdates": [],
            "userType": null,
            "actions": null,
            "fromToDate": {
                "left": 1525132800,
                "right": 1526601600,
                "value": 1526601600,
                "key": 1525132800
            },
            "objectTypeFieldDataList": [
                {
                    "entityType": "TargetingAttributeDTO",
                    "entitySubTypes": [
                        "WOEID"
                    ],
                    "entityAttrs": [
                        "status",
                        "exclude",
                        "targetingType",
                        "value",
                        "bidSet",
                        "adParamValues",
                        "landingUrl",
                        "customParameters",
                        "finalUrl",
                        "trackingUrl",
                        "modifier",
                        "mobileFinalUrl"
                    ]
                }
            ]
        },
        "errors": null
    }
}

Example 4: Using Parent campaign ID filter

Request:

{

  "filters": [
      { "field": "ChangeDate","operator": "between", "from": "2018-04-01", "to": "2018-05-17"},
      { "field": "AdvertiserID","operator": "=", "value":"1495309"},
      { "field": "CampaignId","operator": "=", "value":"365687152"}
  ]
}

Response:

{
    "errors": null,
    "timestamp": "2018-05-17 22:07:07",
    "response": {
        "rows": [
            {
                "objectId": "365687152",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "customParameters",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525392175000,
                "action": "UPDATE",
                "oldValue": "null",
                "newValue": "[key:param1, value:pct48, key:param2, value:coupon, key:param3, value:p3]",
                "campaignId": 365687152,
                "adGroupId": null
            },
            {
                "objectId": "9694760289",
                "objectType": "AdGroup",
                "objectSubType": null,
                "objectField": "biddingStrategy",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525127246000,
                "action": "UPDATE",
                "oldValue": "null",
                "newValue": "DEFAULT",
                "campaignId": 365687152,
                "adGroupId": 9694760289
            },
            {
                "objectId": "9694760289",
                "objectType": "AdGroup",
                "objectSubType": null,
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525127231000,
                "action": "UPDATE",
                "oldValue": "ACTIVE",
                "newValue": "PAUSED",
                "campaignId": 365687152,
                "adGroupId": 9694760289
            },
            {
                "objectId": "9694760289",
                "objectType": "AdGroup",
                "objectSubType": null,
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525127211000,
                "action": "CREATE",
                "oldValue": null,
                "newValue": null,
                "campaignId": 365687152,
                "adGroupId": null
            },
            {
                "objectId": "365687152",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "startDateStr",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525127211000,
                "action": "UPDATE",
                "oldValue": "null",
                "newValue": "2018-04-30",
                "campaignId": 365687152,
                "adGroupId": null
            },
            {
                "objectId": "305151559257",
                "objectType": "TargetingAttribute",
                "objectSubType": "SHARED_SET",
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525127041000,
                "action": "CREATE",
                "oldValue": null,
                "newValue": null,
                "campaignId": 365687152,
                "adGroupId": null
            },
            {
                "objectId": "365687152",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "biddingStrategy",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1524612229000,
                "action": "UPDATE",
                "oldValue": "null",
                "newValue": "OPT_ENHANCED_CPC",
                "campaignId": 365687152,
                "adGroupId": null
            },
            {
                "objectId": "365687152",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "isNativeChannel",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "I",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1524612229000,
                "action": "UPDATE",
                "oldValue": "true",
                "newValue": "false",
                "campaignId": 365687152,
                "adGroupId": null
            }
        ],
        "accountHistoryRequest": {
            "startIndex": null,
            "maxRows": null,
            "entityIds": [],
            "entityTypes": null,
            "entityAttrs": null,
            "advertiserIds": [
                1495309
            ],
            "campaignIds": [
                365687152
            ],
            "adgroupIds": [],
            "entitySubTypes": null,
            "sortAttr": null,
            "sortOrder": null,
            "userUpdates": [],
            "userType": null,
            "actions": null,
            "fromToDate": {
                "left": 1522540800,
                "right": 1526601600,
                "value": 1526601600,
                "key": 1522540800
            },
            "objectTypeFieldDataList": [
                {
                    "entityType": "AdvertiserDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "mdmAdvertiserName",
                        "tier",
                        "amContact",
                        "vatId",
                        "suspendReason",
                        "trackingUrl",
                        "channel",
                        "timezone"
                    ]
                },
                {
                    "entityType": "CampaignDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "campaignName",
                        "budget",
                        "spendCap",
                        "budgetType",
                        "trackingUrl",
                        "isNativeChannel",
                        "isSearchChannel",
                        "subChannelModifier",
                        "customParameters",
                        "biddingStrategy",
                        "startDateStr",
                        "endDateStr",
                        "subChannel"
                    ]
                },
                {
                    "entityType": "AdGroupDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "adGroupName",
                        "startDateStr",
                        "endDateStr",
                        "bidSet",
                        "ecpaGoal",
                        "biddingStrategy",
                        "customParameters",
                        "trackingUrl"
                    ]
                },
                {
                    "entityType": "AdDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "title",
                        "title2",
                        "description",
                        "imageUrl",
                        "imageUrlHQ",
                        "imageUrlLarge",
                        "impressionTrackingUrl",
                        "trackingUrl",
                        "callToActionText",
                        "contentUrl",
                        "displayUrl",
                        "landingUrl",
                        "sponsoredBy",
                        "finalUrl",
                        "displayUrlPath1",
                        "displayUrlPath2",
                        "customParameters",
                        "mobileFinalUrl"
                    ]
                },
                {
                    "entityType": "TargetingAttributeDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "exclude",
                        "targetingType",
                        "value",
                        "bidSet",
                        "adParamValues",
                        "landingUrl",
                        "customParameters",
                        "finalUrl",
                        "trackingUrl",
                        "modifier",
                        "mobileFinalUrl"
                    ]
                }
            ]
        },
        "errors": null
    }
}

Example 5: Using an Action filter

Request:

{

  "filters": [
              { "field": "ChangeDate","operator": "between", "from": "2018-05-01", "to": "2018-05-05"},
              { "field": "AdvertiserID","operator": "=", "value":"1495309"},
              { "field": "Action","operator": "=", "value":"Create"}
  ]
}

Response:

{
    "errors": null,
    "timestamp": "2018-05-17 22:12:12",
    "response": {
        "rows": [
            {
                "objectId": "305264712612",
                "objectType": "TargetingAttribute",
                "objectSubType": "WOEID",
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "E",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525463182000,
                "action": "CREATE",
                "oldValue": null,
                "newValue": null,
                "campaignId": 366813830,
                "adGroupId": null
            },
            {
                "objectId": "366813830",
                "objectType": "Campaign",
                "objectSubType": null,
                "objectField": "status",
                "advertiserId": "1495309",
                "user": "user",
                "userType": "E",
                "interfaceType": null,
                "interfaceVersion": null,
                "changeDate": 1525463181000,
                "action": "CREATE",
                "oldValue": null,
                "newValue": null,
                "campaignId": null,
                "adGroupId": null
            }
        ],
        "accountHistoryRequest": {
            "startIndex": null,
            "maxRows": null,
            "entityIds": [],
            "entityTypes": null,
            "entityAttrs": null,
            "advertiserIds": [
                1495309
            ],
            "campaignIds": [],
            "adgroupIds": [],
            "entitySubTypes": null,
            "sortAttr": null,
            "sortOrder": null,
            "userUpdates": [],
            "userType": null,
            "actions": [
                "C"
            ],
            "fromToDate": {
                "left": 1525132800,
                "right": 1525564800,
                "value": 1525564800,
                "key": 1525132800
            },
            "objectTypeFieldDataList": [
                {
                    "entityType": "AdvertiserDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "mdmAdvertiserName",
                        "tier",
                        "amContact",
                        "vatId",
                        "suspendReason",
                        "trackingUrl",
                        "channel",
                        "timezone"
                    ]
                },
                {
                    "entityType": "CampaignDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "campaignName",
                        "budget",
                        "spendCap",
                        "budgetType",
                        "trackingUrl",
                        "isNativeChannel",
                        "isSearchChannel",
                        "subChannelModifier",
                        "customParameters",
                        "biddingStrategy",
                        "startDateStr",
                        "endDateStr",
                        "subChannel"
                    ]
                },
                {
                    "entityType": "AdGroupDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "adGroupName",
                        "startDateStr",
                        "endDateStr",
                        "bidSet",
                        "ecpaGoal",
                        "biddingStrategy",
                        "customParameters",
                        "trackingUrl"
                    ]
                },
                {
                    "entityType": "AdDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "title",
                        "title2",
                        "description",
                        "imageUrl",
                        "imageUrlHQ",
                        "imageUrlLarge",
                        "impressionTrackingUrl",
                        "trackingUrl",
                        "callToActionText",
                        "contentUrl",
                        "displayUrl",
                        "landingUrl",
                        "sponsoredBy",
                        "finalUrl",
                        "displayUrlPath1",
                        "displayUrlPath2",
                        "customParameters",
                        "mobileFinalUrl"
                    ]
                },
                {
                    "entityType": "TargetingAttributeDTO",
                    "entitySubTypes": null,
                    "entityAttrs": [
                        "status",
                        "exclude",
                        "targetingType",
                        "value",
                        "bidSet",
                        "adParamValues",
                        "landingUrl",
                        "customParameters",
                        "finalUrl",
                        "trackingUrl",
                        "modifier",
                        "mobileFinalUrl"
                    ]
                }
            ]
        },
        "errors": null
    }
}

FAQs

What are the possible values for interfaceType and interfaceVersion in the JSON response and what do they represent?

Note that in your request filter, you should not use both interfaceType and interfaceVersion: interfaceType is null, while interfaceVersion could be null or V1, V2, or V3.

What are the possible values for userType in the responses and what do they represent?

I represents internal, meaning that the user is a Verizon Media employee, and E represents external, meaning that the user is a API partner or developer.

Once the change is made, how long does it take to show up via the API?

The change will appear in 1-2 hours.

For the ObjectType field, what objects are supported?

The objects supported include Advertiser, Campaign, AdGroup, Ad, TargetingAttribute, SiteLink, and Keyword.