Account Change History¶
Abstract¶
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.
Overview¶
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 Yahoo Native 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.