<!--
{
  "availability" : [
    "Apple Ads Platform API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Apple-Ads-Platform-API",
  "identifier" : "/documentation/Apple-Ads-Platform-API/Get-change-details-by-detailId",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service Endpoint",
  "symbol" : {
    "kind" : "Web Service Endpoint",
    "modules" : [
      "Apple Ads Platform API"
    ],
    "preciseIdentifier" : "rest:apple-ads-platform-api:get:change-history-{}"
  },
  "title" : "Get Change History Detail"
}
-->

# Get Change History Detail

Retrieve field-level before and after values for a single entity change by its detail ID.

## Discussion

This endpoint returns the complete field-level change record for a single entity within a transaction. The response contains a `details` array of [`ActivityDetail`](/documentation/Apple-Ads-Platform-API/ActivityDetail) objects, each holding a `changes` array of field change objects. Each change object captures the `field` name, `oldValues`, and `newValues` as string arrays. To page through a large `changes` array, use `limit` and `offset`.

What populates `oldValues` and `newValues` depends on the event type that produced the change.

|Event Type|`oldValues`         |`newValues`                                                                                                                      |
|----------|--------------------|---------------------------------------------------------------------------------------------------------------------------------|
|`CREATE`  |Empty array         |Set to values at creation                                                                                                        |
|`UPDATE`  |Previous field value|Updated field value                                                                                                              |
|`DELETE`  |Last known value    |Typically empty [], but may contain system-managed values (for example, deletion flag, status, transaction ID) set at delete time|

## Payload Examples

**Campaign Update:**

### Request

Retrieve field-level details for a campaign update that changed two fields in the same transaction: it re-enables `status` and increases `dailyBudget`.

```
GET https://api.ads.apple.com/v1/change-history/Campaign.444555666.txn_abc123def456
```

### Response

```json
{
 "dataType": "ChangeDetail",
 "pagination": {
   "offset": 0,
   "pageSize": 1,
   "totalCount": 1
 },
 "result": [
   {
     "transactionId": "txn_abc123def456",
     "detailId": "Campaign.444555666.txn_abc123def456",
     "eventType": "UPDATE",
     "entityType": "Campaign",
     "entityId": "444555666",
     "eventTime": "2025-03-15T14:30:00.000Z",
     "userType": "CUSTOMER_API",
     "modifiedBy": "555666777",
     "entityMetaData": {
       "name": "AwayFinder - Summer App Promo"
     },
     "details": [
       {
         "transactionId": "txn_abc123def456",
         "changes": [
           {
             "field": "status",
             "oldValues": [
               "PAUSED"
             ],
             "newValues": [
               "ENABLED"
             ]
           },
           {
             "field": "dailyBudget",
             "oldValues": [
               "50.00"
             ],
             "newValues": [
               "100.00"
             ]
           }
         ]
       }
     ]
   }
 ]
}
```

**Ad Group Create:**

### Request

Retrieve field-level details for a new ad group creation. The `oldValues` field is empty for all fields on `CREATE` events.

```
GET https://api.ads.apple.com/v1/change-history/AdGroup.888999333.txn_def789ghi012
```

### Response

```json
{
 "dataType": "ChangeDetail",
 "pagination": {
   "offset": 0,
   "pageSize": 1,
   "totalCount": 1
 },
 "result": [
   {
     "transactionId": "txn_def789ghi012",
     "detailId": "AdGroup.888999333.txn_def789ghi012",
     "eventType": "CREATE",
     "entityType": "AdGroup",
     "entityId": "888999333",
     "eventTime": "2025-03-10T09:15:00.000Z",
     "userType": "CUSTOMER",
     "modifiedBy": "12345678",
     "entityMetaData": {
       "name": "AwayFinder — Broad Match — US",
       "campaignId": "444555777"
     },
     "details": [
       {
         "transactionId": "txn_def789ghi012",
         "changes": [
           {
             "field": "name",
             "oldValues": [],
             "newValues": [
               "AwayFinder — Broad Match — US"
             ]
           },
           {
             "field": "status",
             "oldValues": [],
             "newValues": [
               "ENABLED"
             ]
           },
           {
             "field": "defaultBidAmount",
             "oldValues": [],
             "newValues": [
               "2.50"
             ]
           },
           {
             "field": "campaignId",
             "oldValues": [],
             "newValues": [
               "444555777"
             ]
           }
         ]
       }
     ]
   }
 ]
}
```

**Keyword Delete:**

### Request

Retrieve field-level details for a deleted keyword. The `newValues` field is empty for all fields on `DELETE` events.

```
GET https://api.ads.apple.com/v1/change-history/Keyword.777888999.txn_jkl345mno678
```

### Response

```json
{
 "dataType": "ChangeDetail",
 "pagination": {
   "offset": 0,
   "pageSize": 1,
   "totalCount": 1
 },
 "result": [
   {
     "transactionId": "txn_jkl345mno678",
     "detailId": "Keyword.777888999.txn_jkl345mno678",
     "eventType": "DELETE",
     "entityType": "Keyword",
     "entityId": "777888999",
     "eventTime": "2025-03-05T11:00:00.000Z",
     "userType": "CUSTOMER_API",
     "modifiedBy": "98765432",
     "entityMetaData": {
       "adGroupId": "888999111",
       "campaignId": "444555666"
     },
     "details": [
       {
         "transactionId": "txn_jkl345mno678",
         "changes": [
           {
             "field": "text",
             "oldValues": [
               "fitness tracker"
             ],
             "newValues": []
           },
           {
             "field": "matchType",
             "oldValues": [
               "BROAD"
             ],
             "newValues": []
           },
           {
             "field": "status",
             "oldValues": [
               "ENABLED"
             ],
             "newValues": []
           }
         ]
       }
     ]
   }
 ]
}
```

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)