Activity logs

The activity log captures changes made to an ad group and who made them. These logs assist in evaluating how specific changes affect campaign strategy. Here's what you need to know about activity logs:

• Activity logs are available only in the REST API.
• Activity is logged for ad groups and ad-group owned bid lists.
• The activity log endpoints enable you to retrieve activity logs as well as create and update notes for individual activity logs.
• Activity log information is rolled up every five minutes and is retrievable through the API 10-15 minutes after the change is logged.
• The maximum lookback period for the activity log endpoints counts the previous three months plus the days in the current month leading up to today.

For instance, in a lookback on January 15 of the current year, all of October, November, and December of the previous year and everything up to January 15 of the current year will be included in the Activity Log. The following table shows the spectrum of one of the shortest to one of the longest lookback periods.

Ad group property changes

To learn more about ad groups, review our Ad groups article. To learn more about ad group properties, review the POST /v3/adgroup documentation.

The following property changes are logged when an ad group is updated. They are not logged when an ad group is created.

IMPORTANT: When an ad group is created through the API, initial property values are not logged, except as noted. When a user creates an ad group through the platform user interface, it does log initial values for most properties. Creating a new ad group through the user interface creates an initial ad group and then updates that ad group's settings to add the other properties throughout the workflow.

Ad group audience

The following properties are logged when updated.

NOTE: The RTBAttributes.AudienceTargeting.AudienceExcluderEnabled property controls the enhanced feature known as Prism.

Ad group budget and goals

The following properties are logged when updated.

Ad group flights

The following properties are logged when updated.

Ad group contract targeting

The following properties are logged when updated.

Ad group associated bid lists

The following properties are logged when a BidList is owned by the ad group. Changes are logged when a BidList is added or removed from AssociatedBidLists, or the bid list is enabled or disabled.

bid list logged property changes

To learn more about bid lists, review our Bid lists article. To learn more about bid list properties, review the POST /v3/bidlist documentation.

BidList and BidLines properties are logged when the BidListOwner is AdGroup.

These properties are logged when the bid list is deleted.

BidLines properties are logged when BidLines are added or removed or when the BidAdjustment for a bid line is updated.

Activity log endpoint summary

Filter activity log information

Activity log information is filterable based on what, when, where, and how data was changed. The following sections highlight filtering capabilities and while they are broken out into separate sections, they can all be used together for a comprehensive filtering strategy.

Filter by what changed

1. Use the POST /v3/activity/query/facets endpoint to generate a summary of all of the grouped Entities changed in the activity log for a specific ad group.
2. Use available Entities from step 1 to filter on changes using the UpdatedIn filter in the POST /v3/activity/query/adgroup call.

The table below details logged activity types, their messaging, and what Entity / UpdatedIn value they roll up into. The UpdatedIn value can be used for filtering.

Here's the HTML table converted to Markdown format:

Dimension enumeration

You can look up bid list dimensions in the BidLines property in POST /v3/bidlist endpoint documentation. All of the properties listed are dimensions, except for BidAdjustment and VolumeControlPriority.

Filter by when the change was made

In the POST /v3/activity/query/adgroup call, use DateTimeStartUtc and DateTimeEndUtc to filter by the timeframe the change was made.

Filter by where the change was made

To filter by where a user made a change, use the Source filter in the POST /v3/activity/query/adgroup endpoint.

The following is a list of the value enumerations and what they indicate.

Filter by who made the change

1. Use the POST /v3/activity/query/facets endpoint to generate an UpdatedBy list of users who changed information for the specified ad group.
2. Use available UpdatedBy from step 1 to filter on changes using the UpdatedBy filter in the POST /v3/activity/query/adgroup call.

Usernames for activity logs with source - other

Create or update an activity log note

Use the Note property to store any additional information you would like to keep with the activity log.

Here's a PUT /v3/activity request example.

{
	"Id": 1234567,
	"Note": "This is a system-applied Koa optimization."
}

Here's a PUT /v3/activity response example.

{
    "Id": 1234567,
    "OwnerAdGroupId": "h3jz8t5",
    "ActivityRollupTimeUtc": "2020-04-15T18:15:00",
    "ActivityTimeUtc": "2020-04-15T18:18:05.473",
    "Message": "Site/App Koa optimization was turned on.",
    "Entity": "Ad Group",
    "Note": "This is a system-applied Koa optimization.",
    "ModifiedByUser": "Koa",
    "HasBidListChanges": false,
    "BidLineChanges": null,
    "Source": "Other"
}

Monitor activity log changes

The first time you request activity logs from the delta endpoint, the response will return the LastChangeTrackingVersion.

Cache this information and on subsequent calls to the endpoint, provide the most recent LastChangeTrackingVersion. Including LastChangeTrackingVersion with the request will allow the endpoint to retrieve the activity log specified in the LastChangeTrackingVersion and all newer activity logs.

First delta call

Here's a POST /v3/delta/activity/query/adgroup request example.

{
	"AdGroupId": "h3jz8t5",
	"ReturnEntireActivity": true,
	"IncludeBidLineDetails": false,
	"LastChangeTrackingVersion": null
}

Here's a POST /v3/delta/activity/query/adgroup response example.

Cache the LastChangeTrackingVersion to use in the request of the next call. The LastChangeTrackingVersion is the same as the most recent activity log Id returned.

{
    "ActivityLogs": null,
    "MoreActivityLogsAvailable": true,
    "ElementIds": null,
    "LastChangeTrackingVersion": 145070029
}

Subsequent delta call

Here's a POST /v3/delta/activity/query/adgroup request example.

Send the cached LastChangeTrackingVersion in the request.

{
	"AdGroupId": "h3jz8t5",
	"ReturnEntireActivity": true,
	"IncludeBidLineDetails": false,
	"LastChangeTrackingVersion": 145070029
}

Here's a POST /v3/delta/activity/query/adgroup response example.

Cache the requested information and the LastChangeTrackingVersion to use in the request of the next call.

{
    "ActivityLogs": [
        {
            "Id": 145070029,
            "OwnerAdGroupId": "h3jz8t5",
            "ActivityRollupTimeUtc": "2020-04-15T18:15:00",
            "ActivityTimeUtc": "2020-04-15T18:18:06.55",
            "Message": "1 item was targeted in the Private Contract rail.",
            "Entity": "Private Contract",
            "Note": null,
            "ModifiedByUser": "user@example.com",
            "HasBidListChanges": true,
            "BidLineChanges": null,
            "Source": "Ui"
        },
        {
            "Id": 145070448,
            "OwnerAdGroupId": "h3jz8t5",
            "ActivityRollupTimeUtc": "2020-04-15T18:15:00",
            "ActivityTimeUtc": "2020-04-15T18:18:05.473",
            "Message": "The ad group was enabled.",
            "Entity": "Ad Group",
            "Note": null,
            "ModifiedByUser": "user@example.com",
            "HasBidListChanges": false,
            "BidLineChanges": null,
            "Source": "Ui"
        },
        {
            "Id": 145071661,
            "OwnerAdGroupId": "h3jz8t5",
            "ActivityRollupTimeUtc": "2020-04-15T18:15:00",
            "ActivityTimeUtc": "2020-04-15T18:18:06.647",
            "Message": "Private Contract target rail was added.",
            "Entity": "Private Contract",
            "Note": null,
            "ModifiedByUser": "user@example.com",
            "HasBidListChanges": false,
            "BidLineChanges": null,
            "Source": "Ui"
        }
    ],
    "MoreActivityLogsAvailable": false,
    "ElementIds": null,
    "LastChangeTrackingVersion": 145071661
}

FAQs

The following is a list of commonly asked questions about the activity log.

What does Stack Ranking Enabled mean?

This is a Solimar feature. In a POST/activity/query/campaign response, the Stack Ranking Enabled message means that a campaign has both AutoAllocatorEnabled and AutoPrioritizationEnabled set to true.